API Estismail

Как устроен API

Через API ваш сайт или CRM работает с аккаунтом без входа в кабинет: загружает макеты, ведёт группы и подписчиков, создаёт рассылки и забирает статистику.

• Адрес списка: https://v1.estismail.com/mailer/<ресурс>.json, одного объекта: https://v1.estismail.com/mailer/<ресурс>/<номер>.json. Только HTTPS.
• Ключ передаётся в заголовке каждого запроса: X-Estis-Auth: ВАШ_КЛЮЧ. Ключ лежит в кабинете, в разделе API. Без ключа или с неверным ключом ответ 401.
• Ответ приходит в JSON. Чтобы получить XML, замените .json на .xml.
• GET получает данные, POST создаёт, PUT изменяет, DELETE удаляет.
• Параметры GET передаются в строке запроса. Параметры POST, PUT и DELETE передаются в теле: как форма (application/x-www-form-urlencoded) или как JSON (Content-Type: application/json). Кодировка UTF-8.
• Неизвестные параметры не вызывают ошибку: API их не учитывает.
• Даты в ответах и фильтрах указываются как время unix в секундах.
• Через API видны и меняются только данные вашего аккаунта. Чужой номер даёт 404.

curl https://v1.estismail.com/mailer/users.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ"

<?php
$ch = curl_init('https://v1.estismail.com/mailer/users.json');
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/users.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
)
print(r.status_code, r.text)

const res = await fetch("https://v1.estismail.com/mailer/users.json", {
  headers: { "X-Estis-Auth": "ВАШ_КЛЮЧ" },
});
console.log(res.status, await res.text());

{
  "user": {
    "login": "shop"
  }
}

Списки: страницы, поля, фильтры

Запросы списков (GET без номера) принимают общие параметры. Какие поля, фильтры и сортировки есть у ресурса, написано в его разделе.

curl -G https://v1.estismail.com/mailer/emails.json \
  -H "X-Estis-Auth: ВАШ_КЛЮЧ" \
  -d list_id=12345 -d limit=20 -d page=2 \
  --data-urlencode 'fields=["id","email","name","status"]'

<?php
$query = http_build_query([
    'list_id' => '12345',
    'limit' => '20',
    'page' => '2',
    'fields' => '["id","email","name","status"]',
]);
$ch = curl_init('https://v1.estismail.com/mailer/emails.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/emails.json",
    headers={"X-Estis-Auth": "ВАШ_КЛЮЧ"},
    params={
        "list_id": "12345",
        "limit": "20",
        "page": "2",
        "fields": '["id","email","name","status"]',
    },
)
print(r.status_code, r.text)

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

Запрос одного объекта (GET с номером) принимает только fields.

Ответы

{
  "name": "Error #20140: Invalid email. Check the validity of the specified email. Details: https://my.estismail.com/settings/api#error_20140",
  "message": "Error #20140: Invalid email. Check the validity of the specified email. Details: https://my.estismail.com/settings/api#error_20140",
  "url": "/mailer/emails.json"
}

Пределы

• До 100 записей за один запрос списка.
• До 10 отправителей в аккаунте.
• Подписчики добавляются без ограничения числа. По умолчанию новому адресу уходит письмо подтверждения; добавить без письма можно на тарифах Premium и Enterprise. Импортом: до 1000 адресов за запрос, с той же проверкой группы, что у импорта файла в кабинете. Если подписчиков стало больше, чем позволяет тариф, отправка закрывается так же, как в кабинете.
• Рассылка через API проходит те же проверки, что в кабинете: отправка не закрыта, получателей не больше, чем подписчиков в тарифе, на тарифах Premium и Enterprise отправитель на своём домене.
• Серии писем: до 100 шагов, до 50 групп входа, до 1000 адресов за один запрос добавления в серию.
• Отдельного ограничения частоты запросов нет.

Вопросы по API: support@estismail.com