Climails · Публичный API

Climails — платформа email- и мультиканальных рассылок. Этот API даёт программный доступ ко всему, что есть в кабинете: отправка писем и сообщений, контакты, списки и сегменты, шаблоны, кампании, события, автоматизации, отправляющие домены, веб-хуки и аналитика.

Как читать эту страницу. Слева — все эндпоинты, сгруппированные по разделам. Кликните на операцию, чтобы увидеть её параметры, тело запроса и примеры ответов. Кнопка TRY выполняет запрос прямо из браузера — вставьте свой API-ключ в поле авторизации (см. «Аутентификация» ниже).

Нужны только письма (регистрация, сброс пароля)?

Не нужно поднимать свой почтовый сервер и не нужно разбираться в контактах, списках, сегментах, кампаниях и автоматизациях — это всё для маркетинговых рассылок по базе. Для транзакционных писем со своим шаблоном достаточно трёх шагов:

1. Подтвердите свой домен — раздел domains: добавьте домен и пропишите выданные DNS-записи (SPF/DKIM/DMARC). Без этого письма либо не уйдут, либо попадут в спам. Делается один раз. 2. Создайте шаблон (по желанию) — раздел templates: POST /templates с вашим HTML и плейсхолдерами вроде {{name}} / {{reset_link}}. В ответ придёт template_id. Можно и без шаблона — слать html прямо в запросе. 3. Отправляйте письма — POST /messages, по одному на каждое событие (регистрация, сброс пароля и т.п.).

Отправка по своему шаблону с подстановкой переменных:

curl -X POST https://api.climails.com/v1/messages \
  -H "Authorization: Bearer sb_live_<prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "[email protected]",
    "from_email": "no-reply@ваш-домен.com",
    "template_id": "tmpl_reset_password",
    "variables": { "name": "Иван", "reset_link": "https://ваш-сайт.com/r/abc" }
  }'

Всё остальное в этой доке (contacts, lists, segments, campaigns, automations, events, webhooks) — опционально и вам сейчас не требуется.

Аутентификация

Все запросы авторизуются Bearer API-ключом: Authorization: Bearer sb_live_<prefix>.<secret>

Ключи создаются в кабинете: Настройки → API-ключи. Каждый ключ привязан к одному рабочему пространству и имеет набор скоупов (например contacts:write, messages:send). Ключ показывается полностью только один раз при создании.

Быстрый старт

Отправить письмо одним запросом:

curl -X POST https://api.climails.com/v1/messages \
  -H "Authorization: Bearer sb_live_<prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "[email protected]",
    "from_email": "hello@ваш-домен.com",
    "subject": "Привет от Climails",
    "html": "<h1>Готово</h1>"
  }'

В ответ придёт 202 с message_id и status: queued. Статус доставки затем можно получить через GET /messages/{id} или ловить веб-хуками. Обязательные поля — только channel и to; from_email должен принадлежать верифицированному отправляющему домену.

Скоупы

Доступ каждого ключа ограничен его скоупами — сервер проверяет их на каждом запросе и возвращает 403 { "error": "scope required: ..." }, если скоупа нет. Скоуп * даёт полный доступ. Право write включает в себя read для того же ресурса.

| Скоуп | Что открывает | |-------|----------------| | contacts:read | Чтение контактов, списков, сегментов, кастомных полей | | contacts:write | Изменение контактов/списков/сегментов, импорт, suppression | | templates:read | Чтение шаблонов и их версий | | templates:write | Создание/изменение/удаление/импорт шаблонов | | campaigns:read | Чтение кампаний и статистики | | campaigns:write | Создание, изменение, запуск/пауза/отмена кампаний | | automations:read | Чтение автоматизаций | | automations:write| Создание/изменение/активация/триггер автоматизаций | | messages:send | Транзакционная отправка и чтение статуса сообщения | | events:write | Приём product-событий | | webhooks:read | Чтение веб-хуков и доставок | | webhooks:write | Управление веб-хуками, тест, реплей доставок | | domains:read | Чтение sending-доменов и DNS-записей | | domains:write | Добавление/верификация доменов, авто-DNS, IP-пулы | | analytics:read | Аналитика по кампаниям и воркспейсу | | pii:read | Email/phone в открытом виде (иначе маскируются) |

Рабочее пространство

Ресурсы, специфичные для рабочего пространства (контакты, сегменты, шаблоны, кампании, автоматизации, домены, веб-хуки), монтируются под /workspaces/{workspace_id}/.... Узнать workspace_id можно через GET /workspaces. API-ключ авторизует операции только в своём рабочем пространстве — запрос с чужим workspace_id вернёт 403.

Транзакционная отправка (POST /messages) и приём событий (POST /events) воркспейс из ключа берут автоматически — путь не параметризуется.

Идемпотентность

Мутирующие запросы принимают заголовок Idempotency-Key (до 64 символов). Повтор с тем же ключом в течение 24 часов вернёт исходный результат, не создавая дубль.

Базовый URL

Production: https://api.climails.com/v1