Email API MailerMail

Транзакционные и массовые письма из вашего кода плюс верификация адресов. Все запросы — JSON поверх HTTPS, ответы — JSON.

Базовый адрес всех методов:

https://api.mailermail.ru/v1

Контракт построен на привычной модели транзакционных Email API (from/to/subject/html/text/attachments) — миграция с типового провайдера во многом сводится к смене хоста и токена; отличия, которые легко пропустить, собраны в разделе «Переезд с UniOne». Машиночитаемая спецификация — openapi.yaml (OpenAPI 3.0), интерактивная версия — Swagger UI.

Проверка доступности

Метод GET /health не требует токена и отвечает {"ok":true} — удобно для мониторинга.

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

Все методы, кроме /health и /unsubscribe, требуют токен. Передайте его в одном из заголовков:

• Api-Token: mm_live_…
• Authorization: Bearer mm_live_…

Если переданы оба заголовка, используется Api-Token.

Формат токена — mm_live_ или mm_test_ и затем от 16 до 64 латинских букв и цифр (регулярное выражение ^mm_(live|test)_[A-Za-z0-9]{16,64}$). Токен другого вида отбивается 401 ещё до поиска в базе.

Токены выпускаются в кабинете (Настройки → API). Каждый токен несёт scope:

• verify — методы верификации (/verify, /verify/batch);
• send — всё остальное (отправка, шаблоны, стоп-лист, логи, вебхуки, домены).

Токен с префиксом mm_test_ работает в песочнице — письма не уходят, подробности в разделе «Песочница».

Ошибки

Успех — HTTP 2xx и "success": true. Ошибка — соответствующий код и тело {"success": false, "errors": ["…"]}. Массив errors содержит человекочитаемые сообщения (в основном на английском); разбирать их текст в коде не стоит — он может меняться, опирайтесь на HTTP-код.

Ошибка валидации отклоняет запрос целиком: если в /send один адрес из to[] некорректен, не уходит ни одно письмо.

Лимиты запросов

На каждый токен — 120 запросов в минуту. Минута календарная (с :00 до :59 по часам сервера), а не скользящая: 120 запросов в конце одной минуты и 120 в начале следующей пройдут оба.

Считается каждый запрос, прошедший проверку токена и scope, — включая ответы 4xx на ошибки валидации и сами ответы 429. Не считаются /health, /unsubscribe, трекинг и запросы с неверным токеном. При превышении метод отвечает 429 с заголовком Retry-After — число секунд до конца текущей минуты (от 1 до 60).

Лимит рассчитан на пакетную работу, а не на поток по одному письму: 120 запросов в минуту — это до 6000 писем через /send (по 50 получателей) и до 120 000 через /batch.

Отдельные лимиты содержимого:

• /send — до 50 получателей, вложения ≤10 МБ суммарно, тело ≤15 МБ;
• /batch — до 500 request'ов, до 1000 писем суммарно;
• /verify/batch — до 100 адресов.

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

Методы /send и /batch принимают заголовок Idempotency-Key (произвольная строка ≤200 символов, длиннее — 422). Это защищает от двойной отправки при сетевых ретраях. Ключ действует в пределах токена: у двух токенов одинаковые ключи не пересекаются.

• Повтор с тем же ключом в течение 24 часов возвращает сохранённые код и тело первого ответа с заголовком Idempotency-Replayed: true. Тело повтора с первым не сравнивается.
• Сохраняются и ответы 4xx: если первый запрос получил 422, исправленный запрос с тем же ключом снова получит тот же 422. Исправили тело — берите новый ключ. Исключения — ответы, которые отбиваются раньше, чем ключ запоминается: 400 (тело не JSON), 413 за тело больше 15 МБ и 429.
• Ответы 5xx не сохраняются, включая 502 «не ушло ни одно письмо»: повтор с тем же ключом действительно повторит отправку.
• Если первый запрос ещё выполняется — параллельный дубль получает 409. Запрос, зависший больше 5 минут, считается брошенным, и ключ можно использовать снова.
• Тот же ключ на другом эндпоинте (сначала /send, потом /batch) — 422.
• Ключ один на весь запрос: отдельных ключей на получателей нет. Если из 50 адресов 3 попали в failed, повтор с тем же ключом вернёт тот же ответ, ничего не отправив, — дошлите эти три адреса новым запросом с новым ключом.

Песочница

Токен с префиксом mm_test_ прогоняет /send и /batch через весь конвейер, но письма физически не уходят. Остальные методы (шаблоны, стоп-лист, вебхуки, домены) с таким токеном работают по-настоящему — это те же данные аккаунта.

• Домен отправителя проверяется так же, как на бою: неподтверждённый домен — 422 в /send и ошибка в responses[i] в /batch.
• Стоп-лист проверяется: адреса из него приходят в skipped, как на бою.
• Остальные получатели получают message_id и попадают в лог со статусом sandbox (GET /messages?status=sandbox).
• В ответе есть "sandbox": true.
• Событий нет вовсе — ни email.sent, ни открытий, ни переходов: вебхуки песочницей не проверить.
• В счёт отправленных писем (GET /stats → usage.sends) не идёт.
• Лимит 120 запросов в минуту и Idempotency-Key действуют как обычно.

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

Синхронная транзакционная отправка: письмо уходит за секунды, у каждого получателя — своё отдельное письмо и свой message_id. Требует scope send. Домен отправителя должен быть подтверждён в аккаунте (иначе 422) — он же даёт DKIM-подпись.

Задайте subject + html и/или text, либо шаблон через template_id — тогда тему и тело берёт шаблон. Переменные {{var}} подставляются из template_variables и to[].substitutions — правила в разделе «Переменные».

Поля тела

Поля options

Шаблон

• template_id принимает UUID или слаг шаблона (слаг — [a-z0-9-], до 64 символов, строчными). template_uuid — только UUID.
• template_id и template_uuid вместе — 422.
• С шаблоном нельзя передавать subject, html и text — 422: тему и тело даёт шаблон.
• Уходит опубликованная версия шаблона. Шаблон, который ни разу не публиковался, — 422 с просьбой опубликовать; неизвестный шаблон — тоже 422. У опубликованной версии нет темы — 422.
• Без category в запросе берётся категория шаблона.
• Если не передать ни одной переменной, плейсхолдеры {{…}} шаблона уйдут получателю как есть — см. «Переменные».

Чего нет и что игнорируется

• Неизвестные поля верхнего уровня игнорируются молча, без ошибки. cc, bcc, metadata и опечатки в именах полей не вызовут 422 — просто ничего не сделают.
• Копий cc/bcc нет: каждый адрес из to[] получает отдельное письмо, где в To стоит только он. Заголовки Cc и Bcc через headers задать нельзя.
• options.send_at на /send — 422: отложенная отправка есть только в /batch.

Ответ /send

Каждый уникальный адрес из to[] получает ровно один исход:

message_ids не совпадают с to[] по позиции

message_id получают только ушедшие письма; пропущенные и неудачные адреса его не получают. Поэтому message_ids[i] — это не to[i], как только хоть один адрес попал в skipped или failed или в to[] был дубль.

Порядок ушедших при этом сохраняется. Сопоставить можно так: уберите из to[] дубли (без учёта регистра, остаётся первое вхождение), затем адреса из skipped[] и failed[] — оставшиеся адреса по порядку соответствуют message_ids. Если нужен надёжный ключ «письмо ↔ ваша запись», передайте его в custom_variables — он вернётся в каждом событии письма — или отправляйте по одному получателю на запрос.

Причины skipped

Если адрес подходит под обе причины, в ответе будет suppressed.

Причины failed

reason — произвольный текст для человека, не перечисление:

• rendered body over 3 MB — после подстановки переменных HTML и текст вместе больше 3 МБ;
• timeout: send budget exceeded, retry these recipients — на весь запрос отводится 60 секунд, и на медленных реле до части адресов очередь не дошла: письма им не отправлялись, их можно слать повторно;
• текст ошибки SMTP (до 254 символов), например SMTP Error: data not accepted. Это ответ нашего реле, а не сервера получателя: /send передаёт письмо реле, а отказ почтового ящика (переполнен, не существует) приходит позже и в failed[] не попадает.

Коды ответа

"success": true значит «запрос обработан», а не «все письма ушли»: проверяйте failed и skipped всегда. После 502 и 503 письма не ушли и ответ не сохранён под Idempotency-Key, поэтому весь запрос можно повторить как есть, с тем же ключом. Если в 502 причина — постоянный отказ реле (код 5xx в reason), повтор не поможет.

message_id ушедшего письма совпадает с message_id в его событиях вебхука и в GET /messages/{uuid}. У пропущенных и неудачных адресов тоже есть свои записи в логе и события email.suppressed/email.failed, но их id в ответе /send не приходит.

Переменные {{var}}

Плейсхолдер {{name}} в subject, html и text заменяется значением переменной. Работает одинаково в письме из шаблона и в письме, собранном прямо в запросе: шаблон не обязателен.

• Имя — [A-Za-z0-9_.], от 1 до 64 символов; пробелы внутри скобок допустимы ({{ name }}). Плейсхолдер с другим именем ({{Имя}}, {{user-name}}) не распознаётся и остаётся в письме как есть.
• Источники: template_variables — для всех получателей, to[].substitutions — для одного. Значение получателя перекрывает общее; null в substitutions не перекрывает.
• Значения — скаляры: строка, число, true/false, null. Объект или массив — 422. true подставится как 1, false и null — как пустая строка. Значение ≤64 КБ, все значения одного словаря вместе ≤256 КБ.
• Значения вставляются без экранирования. Если значение приходит от пользователя и попадает в HTML, экранируйте его сами (htmlspecialchars), иначе < и & сломают вёрстку.

Подстановка включается только переменными

Плейсхолдеры обрабатываются, только если в запросе есть хотя бы одна переменная — непустой template_variables или непустой substitutions у кого-то из получателей. Без переменных все {{…}} уходят получателю дословно, в том числе из шаблона: это сделано, чтобы не портить тела, где двойные скобки — часть текста.

Неизвестная переменная — пустая строка

Если переменные переданы, а для какого-то плейсхолдера значения нет, он превращается в пустую строку, без ошибки и без предупреждения. Опечатка в имени ({{nmae}}) даёт «Здравствуйте, !». Проверяйте, что передаёте все переменные шаблона.

При переезде с UniOne это ловушка: там неизвестная переменная остаётся в письме как есть, и опечатку видно в тестовом письме; здесь она молча исчезает.

Служебных переменных нет. {{unsubscribe_url}}, {{email}} и подобные — обычные имена: без своего значения они станут пустой строкой. Ссылку отписки в тело нужно вставлять самим — см. «Отписка в письме».

Заголовки и метаданные

custom_variables — метаданные письма

Произвольные пары «ключ — значение», которые не попадают в само письмо, а возвращаются в data.custom_variables событий вебхука. Это главный способ связать событие с записью в вашей системе: положите сюда id заказа или пользователя.

• До 10 ключей. Ключ — буквы, цифры, _, ., -, от 1 до 64 символов; ключ из одних цифр ("123") не принимается.
• Значения — только скаляры, и они приводятся к строке: 42 → "42", true → "true", false → "false", null → "". Объект или массив — 422.
• Всё вместе в виде JSON — не больше 2000 байт (кириллица — 2 байта на букву).
• Одно значение на запрос, а не на получателя: у всех писем одного /send метаданные одинаковые. Разные метаданные на разных получателей — разными запросами или через requests[] в /batch.

Возвращаются в событиях email.sent, email.failed, email.suppressed, email.opened, email.clicked. Не возвращаются в email.bounced и email.unsubscribed: эти события подбирают письмо по адресу получателя, а не по самому письму (см. «Типы событий»).

headers — свои заголовки письма

• До 20 заголовков. Имя — латиница, цифры и дефис, начинается с буквы или цифры, до 64 символов.
• Значение — строка (число и true/false тоже примутся и станут "1"/""; null — 422), без переводов строк, до 900 байт. Все заголовки вместе в виде JSON — не больше ~1900 байт.
• Служебные заголовки задать нельзя — 422 (регистр не важен): From, To, Cc, Bcc, Subject, Reply-To, Sender, Return-Path, Message-ID, Date, MIME-Version, Content-Type, Content-Transfer-Encoding, Content-Disposition, DKIM-Signature, DomainKey-Signature, Received, X-Mailer, List-Unsubscribe, List-Unsubscribe-Post, List-Id, List-Post, List-Help, List-Owner, List-Archive, Feedback-ID, Disposition-Notification-To, Return-Receipt-To, Errors-To, Read-Receipt-To, Resent-From, Resent-To, Resent-Cc, Resent-Sender, Resent-Date, Resent-Message-ID.

Отписку в заголовках включают не через headers, а через options.list_unsubscribe или options.unsubscribe_url.

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

Кнопку «Отписаться» почтовые клиенты (Gmail, Яндекс, Mail.ru) рисуют по заголовкам List-Unsubscribe и List-Unsubscribe-Post (RFC 8058, One-Click). На /send заголовки по умолчанию не ставятся; включить их можно двумя способами — они по-разному решают, кто узнаёт об отписке.

list_unsubscribe: true — отписку ведёт MailerMail

• В заголовке — ссылка MailerMail вида https://mailermail.ru/api/v1/u/{token}. Токен один на пару «аккаунт — адрес»: у всех писем одному человеку ссылка одинаковая.
• One-Click (POST от почтового клиента) обрабатывает MailerMail: адрес уходит в стоп-лист с причиной unsubscribed, приходит событие email.unsubscribed, а контакт с этим адресом в кабинете помечается отписавшимся.
• Дальше /send и /batch пропускают этот адрес (skipped, suppressed). Вернуть — DELETE /suppressions.
• GET по этой ссылке (человек открыл её в браузере) показывает страницу с кнопкой подтверждения и сам по себе ничего не меняет: по ссылкам ходят сканеры почтовых шлюзов.

unsubscribe_url — отписку ведёте вы

• Оба заголовка ведут на ваш адрес: List-Unsubscribe: <ваш URL> и List-Unsubscribe-Post: List-Unsubscribe=One-Click. Почтовый клиент шлёт POST на ваш URL с телом List-Unsubscribe=One-Click — ваш обработчик должен его принять.
• MailerMail об этой отписке не узнаёт: ни записи в стоп-листе, ни события. Если хотите, чтобы сервис сам не слал на этот адрес, добавьте его в стоп-лист (POST /suppressions с reason: "unsubscribed").
• list_unsubscribe при этом передавать не нужно — unsubscribe_url включает заголовки сам.
• Только https://, после схемы — от 5 до 300 байт без пробельных символов, двойных кавычек и угловых скобок, иначе 422. mailto: не поддерживается. Используйте только ASCII: кириллицу в адресе кодируйте (%D0%…), иначе заголовок уйдёт закодированным и почтовики его не распознают.

В тело письма ничего не вставляется

Оба способа ставят только заголовки. Ссылки отписки в тексте письма MailerMail не добавляет, плейсхолдера {{unsubscribe_url}} нет — если передаёте переменные, он превратится в пустую строку, если нет — останется в письме дословно. Для массовых писем ссылку в теле ставьте сами, на свою страницу.

В /batch заголовки со ссылкой MailerMail включены по умолчанию и выключаются options.skip_unsubscribe: true; своего unsubscribe_url там нет.

Массовая отправка

Постановка партии писем в очередь: message_ids выдаются сразу, реально отправляет фоновый воркер (латентность до ~5 минут). Объект base задаёт общие поля, поля каждого request их перекрывают. Вложения не поддерживаются — используйте /send.

HTTP всегда 200 (кроме структурных ошибок тела): пер-письмо статусы — в массиве responses[] в порядке requests.

Поля тела

Домены отправителя

Отправлять можно только с подтверждённого домена: если домен из from не проверен, /send отвечает 422, а /batch — ошибкой в responses[i] для каждого такого письма. Это защита от подделки отправителя и требование почтовых провайдеров — без SPF и DKIM письма уходят в спам.

Как подключить домен

1. В кабинете: Настройки → Домены отправителя → Добавить. Мы сгенерируем пару ключей DKIM.
2. Опубликуйте три TXT-записи в DNS вашего домена (их отдаёт и этот метод, и карточка домена в кабинете).
3. Нажмите «Проверить DNS». Записи расходятся до 48 часов — если проверка не прошла сразу, повторите позже.

Добавление и проверка живут в кабинете намеренно: это разовое действие человека с доступом к DNS, а не то, что автоматизируют из кода. Через API домены доступны только на чтение — чтобы интеграция могла убедиться, что домен готов, до отправки, а не ловить 422 в бою.

Статусы

Поля spf, dkim, dmarc показывают, какая именно запись не найдена. checked_at — время последней проверки; у домена, который ещё ни разу не проверялся, он равен null. Раз в сутки мы сами перепроверяем только домены в статусе verified и failed. Домен в pending_dns сам в verified не перейдёт — после публикации записей нажмите «Проверить DNS» в кабинете; опрашивать API в ожидании бесполезно. Домен, простоявший в pending_dns больше 7 дней, удаляется, и GET /domains/{domain} начинает отвечать 404. Метки времени здесь — ISO 8601 со смещением.

GET /domains/{domain} дополнительно отдаёт dns_records — три TXT-записи, которые нужно опубликовать, с подсказкой note к каждой. Записи приходят и для уже подтверждённого домена: пригодится при переезде к другому DNS-провайдеру. Длинный ключ DKIM разбит на части по 255 символов в кавычках — так его принимает большинство DNS-панелей. Метод читает сохранённый результат проверки и сам DNS не опрашивает. Домена нет в аккаунте — 404.

Рекомендуем отдельный поддомен для рассылок (например mail.brand.ru): он изолирует репутацию рассылок от корпоративной почты — проблемы с одним потоком не утянут другой.

Кириллические домены можно запрашивать как есть — /domains/почта.рф и /domains/xn--80a1acny.xn--p1ai вернут одно и то же.

Верификация адресов

Проверка адреса без отправки письма: синтаксис, MX/A домена, ролевые и одноразовые адреса, глобальный реестр недоставляемых, подсказка опечаток. Требует scope verify. Пакетом — до 100 адресов.

Поле тела

Статусы результата

Шаблоны

Хранимые шаблоны письма с переменными {{var}} в теме и теле. При отправке подставляются через template_id (или template_uuid) + template_variables/substitutions. Требует scope send. Лимит — 5000 шаблонов на аккаунт.

Хранилище общее с личным кабинетом. Шаблон, созданный по API, виден и редактируется в разделе «Шаблоны», а письмо, свёрстанное в кабинете, доступно по API — поле source показывает, откуда строка. Поэтому у шаблона есть версии: send и batch отправляют опубликованную версию, а не текущий черновик. Через API шаблон публикуется сам — при создании и при правке subject/html/text; публиковать вручную нужно только то, что правили в кабинете.

Поля создания / обновления

Методы

• GET /templates — список, новые первыми: ?limit= от 1 до 100 (по умолчанию 50), ?offset=. Тел в списке нет. uuid может быть null — у старого письма из кабинета, которому не удалось выдать ключ; такой шаблон по API не адресуется.
• GET /templates/{uuid} — шаблон целиком, с html/text черновика и признаком has_unpublished_changes.
• POST /templates — создать, ответ 201 с объектом template.
• PATCH /templates/{uuid} — обновить любое подмножество полей; после правки обязано остаться хотя бы одно тело. Ответ без обёртки template и без uuid — только состояние после правки: status, version, has_unpublished_changes.
• POST /templates/{uuid}/publish — опубликовать текущий черновик, тело не нужно.
• DELETE /templates/{uuid} — удалить, ответ {"success": true}.

В пути — только UUID. Слаг адресует шаблон лишь в template_id при отправке: GET /templates/order-ok вернёт 404. Храните у себя uuid.

Когда правка публикуется

• Правка subject, html или text публикуется сама, если не передать "publish": false. Если новое содержимое совпадает с опубликованным, новой версии не будет.
• Правка только name, category или slug не публикуется: иначе переименование по API отправило бы подписчикам недописанный в кабинете черновик.
• Если тело сохранилось, а публикация не прошла, PATCH отвечает 500 — повторите POST /templates/{uuid}/publish. До этого уходит прежняя версия.
• Тело шаблона, собранного в блочном конструкторе кабинета, по API не правится — 422; имя, тему, категорию и слаг — можно.

Шаблон, за который держится рассылка, запущенная до появления версий, править и удалять нельзя (409): она читает его на каждом письме. Занятый слаг — тоже 409. Метки created_at/updated_at у шаблонов — в формате YYYY-MM-DD HH:MM:SS по московскому времени, без смещения.

html/text в ответе — это черновик, а отправляется опубликованная версия. Их видно расходящимися, когда письмо правят в кабинете и не публикуют. Признак — has_unpublished_changes в GET и в ответе PATCH: если он true, уйдёт не то тело, что вы прочитали, — опубликуйте (POST /templates/{uuid}/publish). Само по себе status: "published" говорит лишь о том, что опубликованная версия существует.

Стоп-лист (suppressions)

Адреса, на которые сервис не отправит письмо: /send и /batch отдают их в skipped с причиной suppressed. Пополняется автоматически (отказы, жалобы, отписки) и вручную через API. Требует scope send. Адреса хранятся в нижнем регистре.

• GET /suppressions — список, новые первыми: ?limit= от 1 до 1000 (по умолчанию 100), ?offset=, ?reason=. Ответ — {success, total, suppressions: [{email, reason, created_at}]}.
• GET /suppressions?email=x@y.ru — проверка одного адреса: {success, email, suppressed, reason, created_at}; если адреса в списке нет — suppressed: false, reason и created_at равны null. Некорректный адрес — 422.
• POST — добавить {emails: […≤1000], reason?}. Ответ — {success, added, reason, invalid?}. added — число обработанных корректных адресов, включая уже бывшие в списке; причина у них перезаписывается переданной (по умолчанию manual).
• DELETE — убрать (снять блокировку) {emails: […≤1000]}. Ответ — {success, removed, invalid?}, где removed — сколько адресов действительно было в списке.

Некорректные адреса в POST/DELETE не прерывают запрос — они перечислены в invalid. Если корректных нет вовсе — 422 с тем же invalid. Дубли внутри запроса схлопываются. created_at — формат YYYY-MM-DD HH:MM:SS, московское время.

DELETE снимает только стоп-лист аккаунта. Причину known_bounce (общий реестр недоставляемых) через API не снять — только в кабинете: Контакты → Заблокированные, и сейчас это действует только на /send.

Причины (reason)

Логи и статистика

Лог отправок хранится 30 дней. Требует scope send.

Фильтры GET /messages

GET /messages/{uuid} возвращает одно сообщение, а для писем из /batch — ещё и состояние очереди (попытки, время отправки). GET /stats?days=7|30 отдаёт агрегаты по статусам, дням и категориям + суммарный объём проверок и отправок.

Отписка

Публичный endpoint по стандарту RFC 8058 (One-Click). Токен не нужен: длинную ссылку /unsubscribe?t=&e=&s= санкционирует HMAC-подпись, короткую /u/{token}, которая стоит в заголовках, — случайный токен, выданный на пару «аккаунт — адрес». Его вызывают почтовые клиенты (кнопка «Отписаться» в Gmail/Yandex) и получатели.

Ссылка автоматически проставляется в заголовок List-Unsubscribe при массовой отправке (в /batch — по умолчанию; в /send — по options.list_unsubscribe). POST добавляет адрес в стоп-лист (reason=unsubscribed), снимает подписку в кабинете и порождает событие email.unsubscribed; GET отдаёт человеку страницу подтверждения и ничего не меняет. Когда отписку ведёт ваш собственный unsubscribe_url, этот endpoint не участвует — см. «Отписка в письме».

Самостоятельно формировать эти ссылки не нужно — сервис вставляет их сам. В письмах они ведут на основной домен (https://mailermail.ru/api/v1/u/…), а не на api.: получателю привычнее видеть знакомый адрес, и репутация этих ссылок уже набрана.

Вебхуки

Мы шлём POST на ваш адрес пачками до 500 событий, очередь разбирается каждую минуту. Требует scope send; до 20 вебхуков на аккаунт (21-й — 422). Управлять ими можно и в кабинете: Настройки → Вебхуки.

Поля создания и правки

Ответы

• POST /webhooks → 201: объект webhook, а секрет — на верхнем уровне, в поле secret. Идентификатор вебхука — webhook.webhook_id (не uuid); его и подставляйте в путь /webhooks/{uuid}.
• GET /webhooks → {success, total, webhooks: […]}, новые первыми.
• GET /webhooks/{uuid} → {success, webhook, queue}; queue — счётчики строк очереди доставки: pending (ждут доставки), sent и failed (эти два хранятся 7 дней).
• PATCH /webhooks/{uuid} — любое из url, events, enabled; ответ {success, webhook}. Ни одного из трёх полей — 422. Смена url обнуляет счётчик отказов и снимает авто-паузу (но не ручное выключение); enabled: true включает вебхук и обнуляет счётчик.
• DELETE /webhooks/{uuid} → {success, deleted: "<webhook_id>"}; недоставленные события удаляются вместе с ним.
• POST /webhooks/{uuid}/rotate_secret → {success, webhook, secret, note}, тело запроса не нужно. Старый секрет перестаёт действовать сразу, в том числе для событий, которые уже ждут повторной доставки.
• POST /webhooks/{uuid} → 405: для правки — PATCH.

Секрет показывается один раз — при создании и при rotate_secret; дальше в ответах только маска secret_hint (первые 8 символов). Потеряли — перевыпустите.

Поля объекта webhook

created_at и last_delivery_at здесь — в формате MySQL YYYY-MM-DD HH:MM:SS по московскому времени, без смещения, а не ISO 8601, как в событиях.

Доставка и подпись

Каждая доставка — POST с JSON-телом {"events": [ … ]}, в пачке от 1 до 500 событий одного вебхука.

Заголовки запроса

Проверка подписи

MailerMail-Signature = HMAC-SHA256 от сырого тела запроса, в hex нижним регистром. Ключ — строка секрета как есть, все 64 символа: не декодируйте её из hex в байты. Префикса вроде sha256= нет, метки времени в подписи нет.

• Считайте подпись по байтам тела до разбора JSON: пересобранный JSON отличается пробелами и экранированием, и подпись не сойдётся.
• Сравнивайте функцией постоянного времени (hash_equals, crypto.timingSafeEqual).
• Защиты от повторной отправки перехваченного запроса подпись не даёт — отсекайте повторы по event_id.

Ответ приёмника и повторы

• Успех — любой 2xx. Тело ответа игнорируется. Редиректы (3xx) не выполняются и считаются неудачей.
• На соединение даётся 5 секунд, на весь ответ — 15. Отвечайте сразу, обработку делайте после ответа.
• Неудачная пачка повторяется через 1, 4, 8, 16 и 32 минуты; у события — около 6 попыток, после чего оно помечается недоставленным. Счётчик попыток пачки берётся по самому свежему событию в ней, поэтому старое событие, попавшее в пачку с новыми, может получить больше попыток и повтор раньше расписания.
• При повторе пачка может собраться иначе: к старым событиям добавятся новые, а часть может уйти в другой пачке. Не полагайтесь ни на состав пачки, ни на MailerMail-Delivery.
• Дедупликация — по event_id: одно событие может прийти дважды, если ответ вашего приёмника до нас не дошёл.
• 5 неудачных доставок подряд ставят вебхук на паузу (paused_reason: "5 неудачных доставок подряд"). Считаются доставки, а не события: пока события идут потоком, попытка случается каждую минуту, и недоступный приёмник уходит на паузу примерно через 5 минут; одиночное событие — примерно через полчаса. Включить обратно — PATCH {"enabled": true}, смена url или кнопка в кабинете.

Пока вебхук на паузе, новые события в его очередь не попадают — восстановить их потом нельзя. События, уже стоявшие в очереди, ждут включения, но не больше суток с момента самого события (а не паузы); после этого они помечаются недоставленными. История событий письма всегда доступна через GET /messages/{uuid}/events (30 дней) независимо от подписок.

Типы событий

Поля события

data по типам

bounce_type

smtp_code — трёхзначный код ответа сервера строкой ("550", не расширенный "5.1.1"); если кода в ответе не нашлось, ключа нет. Текста ответа почтового сервера в событии нет намеренно: в нём имена наших серверов и внутренние идентификаторы.

message_id в событиях

• email.sent, email.opened, email.clicked — тот же message_id, что вернул /send или /batch. У /batch так же и email.failed, если письмо не ушло из очереди.
• email.suppressed и email.failed по адресам из skipped[]/failed[] несут новый UUID, которого в ответе не было: сопоставляйте их по email и custom_variables.
• email.bounced и email.unsubscribed приходят не из письма, а из внешних источников, поэтому письмо подбирается по адресу: последнее успешно отправленное через API на этот адрес за 7 дней (отказ) или за 30 дней (отписка). Отсюда attribution: "by-address": это догадка, а не факт. Для отписки письма может не найтись — тогда message_id: null, а category нет.

Ограничения, о которых важно знать

• email.bounced для писем Email API сейчас почти не приходит. Отказы разбираются по журналам рассылок кабинета, и только для контактов их списков. Событие появится, лишь если адрес, получивший ваше письмо через API за последние 7 дней, отказал в рассылке из кабинета того же аккаунта. Отказ самого API-письма события не порождает.
• email.complained сейчас не отправляется никогда. Жалобы через FBL обрабатываются: адрес попадает в стоп-лист с причиной complained и дальше пропускается. Следить за жалобами можно через GET /suppressions.
• Песочница (mm_test_) событий не порождает вовсе.

История событий одного письма — GET /messages/{uuid}/events, до 500 событий за 30 дней. Поля там называются иначе: type вместо event и created_at вместо timestamp, а пустой data приходит как {}.

Трекинг открытий и переходов

В HTML-письмо можно вшить пиксель открытия и обернуть ссылки редиректом — тогда приходят события email.opened и email.clicked. Управляют этим два флага в options:

Транзакционному письму трекинг обычно не нужен — код подтверждения и счёт незачем считать пикселем, — поэтому в /send он выключен. В массовой рассылке наоборот: без статистики открытий она бессмысленна.

Трекинг работает только в HTML-версии: ссылки в текстовой версии не оборачиваются, а письмо без html остаётся без пикселя. Пиксель ставится перед </body>, а если его нет — в конец HTML. Обёрнутая ссылка ведёт на https://mailermail.ru/api/v1/t/c/… и отвечает редиректом 302 на исходный адрес; подпись в ссылке покрывает и сам адрес, подменить его нельзя.

Какие ссылки не оборачиваются

• с атрибутом data-mm-no-track у тега <a>;
• не http:// и не https://: mailto:, tel:, якоря #…, относительные адреса;
• с {{ в адресе — неподставленная переменная (так бывает, когда переменные не переданы вовсе);
• служебные ссылки MailerMail — отписка https://mailermail.ru/api/v1/u/… и уже обёрнутые https://mailermail.ru/api/v1/t/…;
• адрес длиннее 1500 символов;
• все ссылки письма, если HTML больше 512 КБ, — пиксель при этом всё равно ставится;
• теги <a> без href.

Известная проблема: адрес с пробелом, ", < или > внутри (например, неэкранированный пробел в параметре) оборачивается, но по клику отвечает 400 — получатель увидит битую ссылку. Кодируйте такие символы в адресах (%20) или ставьте на ссылку data-mm-no-track.

Дедупликация и сроки

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

События трекинга приходят, пока письмо хранится в логе, — 30 дней после отправки. Письма песочницы событий не порождают.

Переезд с UniOne

Модель та же — JSON поверх HTTPS, переменные {{var}}, вебхуки о событиях писем, — но в нескольких местах поведение отличается так, что ошибка не видна сразу. Проверьте эти пункты до переключения.