Как отправить email-рассылку через API

Как отправить рассылку из своей системы: загрузить письмо, собрать получателей, запустить и забрать результат. Подробности по каждому вызову есть в разделах ресурсов.

Загрузите макет письма

HTML письма передаётся в body. Подвал с отпиской рассылка добавит сама: ваш подвал макета (footer), если его нет, подвал аккаунта из настроек, иначе стандартный. Разложить макеты по папкам можно в разделе Папки макетов.

curl https://v1.estismail.com/mailer/makets.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -d title="Октябрьская распродажа" \
  --data-urlencode body@letter.html

<?php
$ch = curl_init('https://v1.estismail.com/mailer/makets.json');
curl_setopt_array($ch, [
    CURLOPT_POSTFIELDS => http_build_query([
        'title' => 'Октябрьская распродажа',
        'body' => file_get_contents('letter.html'),
    ]),
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.post(
    "https://v1.estismail.com/mailer/makets.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    data={
        "title": "Октябрьская распродажа",
        "body": open("letter.html", encoding="utf-8").read(),
    },
)
print(r.status_code, r.text)

import { readFileSync } from "node:fs";

const res = await fetch("https://v1.estismail.com/mailer/makets.json", {
  method: "POST",
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
  body: new URLSearchParams({
    title: "Октябрьская распродажа",
    body: readFileSync("letter.html", "utf8"),
  }),
});
console.log(res.status, await res.text());

Ответ 201: номер макета

{"id":4321}

Создайте группу

curl https://v1.estismail.com/mailer/lists.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -d title="Покупатели октября" \
  -d subscribe_link=https://shop.example.com

<?php
$ch = curl_init('https://v1.estismail.com/mailer/lists.json');
curl_setopt_array($ch, [
    CURLOPT_POSTFIELDS => http_build_query([
        'title' => 'Покупатели октября',
        'subscribe_link' => 'https://shop.example.com',
    ]),
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.post(
    "https://v1.estismail.com/mailer/lists.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    data={
        "title": "Покупатели октября",
        "subscribe_link": "https://shop.example.com",
    },
)
print(r.status_code, r.text)

const res = await fetch("https://v1.estismail.com/mailer/lists.json", {
  method: "POST",
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
  body: new URLSearchParams({
    title: "Покупатели октября",
    subscribe_link: "https://shop.example.com",
  }),
});
console.log(res.status, await res.text());

Ответ 201: номер группы

{"id":12345}

Добавьте подписчиков

Каждый адрес передаётся отдельным запросом. Новому адресу уходит письмо «подтвердите подписку», письма рассылок он получит после подтверждения. На тарифах Premium и Enterprise можно добавить без письма подтверждения: activation_letter=0. Много адресов сразу передаются импортом, до 1000 за запрос.

curl https://v1.estismail.com/mailer/emails.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -d email=anna@example.com -d list_id=12345 \
  -d name="Анна" -d city="Киев" -d activation_letter=0

<?php
$ch = curl_init('https://v1.estismail.com/mailer/emails.json');
curl_setopt_array($ch, [
    CURLOPT_POSTFIELDS => http_build_query([
        'email' => 'anna@example.com',
        'list_id' => '12345',
        'name' => 'Анна',
        'city' => 'Киев',
        'activation_letter' => '0',
    ]),
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.post(
    "https://v1.estismail.com/mailer/emails.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    data={
        "email": "anna@example.com",
        "list_id": "12345",
        "name": "Анна",
        "city": "Киев",
        "activation_letter": "0",
    },
)
print(r.status_code, r.text)

const res = await fetch("https://v1.estismail.com/mailer/emails.json", {
  method: "POST",
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
  body: new URLSearchParams({
    email: "anna@example.com",
    list_id: "12345",
    name: "Анна",
    city: "Киев",
    activation_letter: "0",
  }),
});
console.log(res.status, await res.text());

Ответ 201: номер подписчика

{"id":67890}

Проверьте отправителя

Письма уходят от подтверждённого отправителя. Без sender_email_id рассылка берёт отправителя по умолчанию. Записи DNS для домена отправителя (DKIM, SPF, DMARC) берите в разделе Домены.

curl -G https://v1.estismail.com/mailer/senderemails.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  --data-urlencode 'fields=["id","email","approved","default"]'

<?php
$query = http_build_query([
    'fields' => '["id","email","approved","default"]',
]);
$ch = curl_init('https://v1.estismail.com/mailer/senderemails.json' . '?' . $query);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.get(
    "https://v1.estismail.com/mailer/senderemails.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    params={
        "fields": '["id","email","approved","default"]',
    },
)
print(r.status_code, r.text)

const params = new URLSearchParams({
  fields: '["id","email","approved","default"]',
});
const res = await fetch("https://v1.estismail.com/mailer/senderemails.json?" + params, {
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
});
console.log(res.status, await res.text());

Ответ 200

{
  "sender_emails": [
    {
      "id": 5501,
      "email": "news@shop.example.com",
      "approved": 1,
      "default": 1
    }
  ]
}

Создайте рассылку

Без date рассылка начнётся в течение минуты, с date в будущем начнётся в это время.

curl https://v1.estismail.com/mailer/sends.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -d maket_id=4321 -d letter_title="Октябрьская распродажа" \
  -d included_lists='[12345]'

<?php
$ch = curl_init('https://v1.estismail.com/mailer/sends.json');
curl_setopt_array($ch, [
    CURLOPT_POSTFIELDS => http_build_query([
        'maket_id' => '4321',
        'letter_title' => 'Октябрьская распродажа',
        'included_lists' => '[12345]',
    ]),
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.post(
    "https://v1.estismail.com/mailer/sends.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    data={
        "maket_id": "4321",
        "letter_title": "Октябрьская распродажа",
        "included_lists": "[12345]",
    },
)
print(r.status_code, r.text)

const res = await fetch("https://v1.estismail.com/mailer/sends.json", {
  method: "POST",
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
  body: new URLSearchParams({
    maket_id: "4321",
    letter_title: "Октябрьская распродажа",
    included_lists: "[12345]",
  }),
});
console.log(res.status, await res.text());

Ответ 201: номер рассылки

{"id":290701}

Следите за статусом

curl -G https://v1.estismail.com/mailer/sends/290701.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  --data-urlencode 'fields=["id","status","count"]'

<?php
$query = http_build_query([
    'fields' => '["id","status","count"]',
]);
$ch = curl_init('https://v1.estismail.com/mailer/sends/290701.json' . '?' . $query);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.get(
    "https://v1.estismail.com/mailer/sends/290701.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    params={
        "fields": '["id","status","count"]',
    },
)
print(r.status_code, r.text)

const params = new URLSearchParams({
  fields: '["id","status","count"]',
});
const res = await fetch("https://v1.estismail.com/mailer/sends/290701.json?" + params, {
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
});
console.log(res.status, await res.text());

Ответ 200: status 0 запланирована, 1 идёт, 4 завершена

{
  "id": 290701,
  "count": 1520,
  "status": 1
}

Заберите статистику

curl -G https://v1.estismail.com/mailer/sendstatistics/290701.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  --data-urlencode 'fields=["id","common","errors"]'

<?php
$query = http_build_query([
    'fields' => '["id","common","errors"]',
]);
$ch = curl_init('https://v1.estismail.com/mailer/sendstatistics/290701.json' . '?' . $query);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-Estis-Auth: ВАШ_КЛЮЧ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $response;

import requests

r = requests.get(
    "https://v1.estismail.com/mailer/sendstatistics/290701.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    params={
        "fields": '["id","common","errors"]',
    },
)
print(r.status_code, r.text)

const params = new URLSearchParams({
  fields: '["id","common","errors"]',
});
const res = await fetch("https://v1.estismail.com/mailer/sendstatistics/290701.json?" + params, {
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
});
console.log(res.status, await res.text());