API Reference

Базовый URL: https://api.mail.synapsea.agency. Аутентификация: Authorization: Bearer sm_live_... или заголовок X-Synapsea-Key: sm_live_....

Отправка писем

POST/v1/emails

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

Body:

json

{
  "from": "noreply@example.ru",
  "to": "user@example.com",
  "subject": "Subject",
  "html": "<p>Body</p>",
  "text": "Body",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "reply_to": "reply@example.ru",
  "tags": ["onboarding", "welcome"],
  "headers": { "X-Custom-Header": "value" },
  "bulk": false
}

Поле bulk: true помечает письмо как массовую рассылку — анонс, промо, напоминание об окончании пробного периода. В такое письмо добавляется заголовок List-Unsubscribe с однокликовой отпиской (RFC 8058), и на него действуют отписки получателей. Транзакционные письма — коды подтверждения, чеки, уведомления — отправляйте без этого поля: ссылка отписки в них навредила бы пользователю, отказавшись от кода входа, он потеряет доступ к аккаунту. Отписка от рассылки на транзакционные письма не влияет.

Массовые рассылки допускаются только при наличии согласия получателей — см. Правила допустимого использования. Объём согласуется заранее: превышение суточного лимита писем с одинаковой темой возвращает 429.

Response (202):

json

{ "id": "em_a1b2c3d4...", "status": "queued" }

POST/v1/emails/batch

Отправить до 100 писем за один запрос.

GET/v1/emails/:id

Получить детали письма и его события доставки.

Управление доменами

GET/v1/domains

Список подтверждённых доменов проекта.

POST/v1/domains

Добавить домен (возвращает DNS-записи для добавления).

POST/v1/domains/:id/verify

Проверить DNS-записи и подтвердить домен.

DELETE/v1/domains/:id

Удалить домен.

Suppression list

GET/v1/suppressions

Получить адреса в стоп-листе.

DELETE/v1/suppressions/:email

Удалить адрес из стоп-листа (email в URL-encoded виде).

Аналитика

GET/v1/analytics/overview

Агрегированные метрики за сегодня/неделю/месяц.

GET/v1/analytics/timeseries

Посуточная статистика за 30 дней.

Статусы письма

Статус возвращается в GET /v1/emails/:id и в поле status вебхуков:

queued — принято и поставлено в очередь отправки
sending — передаётся почтовому серверу получателя
sent — сервер получателя принял письмо
delivered — доставка подтверждена (приходит не от всех почтовых служб)
bounced — ящика не существует — адрес добавлен в стоп-лист
rejected — почтовая служба отклонила письмо по своей политике или репутации отправителя; ящик существует, адрес НЕ подавляется
complained — получатель отметил письмо как спам
failed — отправка не состоялась на нашей стороне: домен не подтверждён, все получатели в стоп-листе

Различие bounced и rejected принципиально для чистки базы: bounced означает, что адреса не существует и слать на него больше не нужно. rejected — что письмо не приняли по причинам, к адресу отношения не имеющим, и удалять такого получателя из своей базы нельзя. Мы повторяем такие письма автоматически несколько раз с нарастающей задержкой.

Прогрев и темп отправки

Репутация отправителя нарабатывается отдельно для каждой почтовой службы получателя, поэтому новый проект наращивает объём постепенно. Пока идёт прогрев, письма сверх суточной нормы по конкретной почтовой службе не теряются, а откладываются и уходят позже — в событиях это видно как deferred. Если планируете объём заметно выше обычного, предупредите нас заранее: внеплановый всплеск почтовые службы воспринимают как рассылочный и ограничивают доставку всему отправляющему узлу.

Rate limits

По умолчанию: 60 запросов/сек на проект для HTTP API, 300 писем/сек через SMTP. При превышении — HTTP 429. Увеличение лимитов на тарифах Pro и Scale — по запросу.

Ошибки

Все ошибки возвращаются в формате:

json

{ "error": "Error description" }

Коды:

400 — невалидный payload
401 — нет/неверный API-ключ
403 — домен не подтверждён
429 — превышен rate limit
500 — внутренняя ошибка

Поле code в ответе:

DOMAIN_NOT_VERIFIED — домен отправителя не подтверждён — завершите настройку DNS
SUBSCRIPTION_REQUIRED — нет активной подписки на проекте
RECIPIENT_IN_SUPPRESSION_LIST — все получатели в стоп-листе
BULK_LIMIT_EXCEEDED — превышен суточный лимит писем с одинаковой темой — согласуйте объём рассылки
SENDING_PAUSED — отправка по проекту приостановлена — напишите на abuse@synapsea.agency
QUOTA_EXCEEDED — исчерпана суточная или месячная квота тарифа

Свежий список всех эндпоинтов и примеры запросов/ответов доступен в dashboard после входа.