Mailer API — инструкция для клиента

Через выданный вам токен можно запускать отправку писем. Вы передаёте только адресата, ссылку и несколько переменных — всё остальное (шаблон, тема, отправитель, доставка) настроено на нашей стороне.

База API: https://grzl.cc
Авторизация: заголовок Authorization: Bearer <ваш_токен> в каждом запросе.
Токен — секрет. Не публикуйте его. При компрометации сообщите нам — отзовём.
Один токен на несколько человек. Токеном может пользоваться вся ваша команда — это нормально. В каждом запросе передавайте Telegram id и username того, кто запускает именно эту отправку (идут только в учёт, в письмо не попадают). Квота и лимит запросов — общие на токен (их делят все, кто им пользуется).

1. Справочник: страны и сервисы

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

GET /api/v1/catalog
Authorization: Bearer <токен>

Ответ:

{
  "countries": {
    "PL": { "flag": "🇵🇱", "services": ["myemail.pl", "testshop.pl"] },
    "DE": { "flag": "🇩🇪", "services": ["myemail.de", "testshop.de"] }
  }
}

2. Запуск отправки

POST /api/v1/send
Authorization: Bearer <токен>
Content-Type: application/json

Тело запроса:

Поле	Обяз.	Описание
`country`	да	Код страны из каталога (напр. `PL`)
`service`	да	Сервис из каталога этой страны (напр. `myemail.pl`)
`email`	да	E-mail получателя
`link`	да	Ссылка (`http(s)://…`) — подставляется в кнопку письма
`id`	да	Telegram userid (число) того, кто запускает отправку — для учёта, в письмо не идёт
`username`	да	Telegram @username того же человека — для учёта, в письмо не идёт
`price`	нет	Цена товара без валюты (напр. `199`) → `PRICE`
`predmetname`	нет	Название товара → `PNAME`

Пример:

curl -X POST https://grzl.cc/api/v1/send \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "PL",
    "service": "myemail.pl",
    "email": "[email protected]",
    "link": "https://target.example/offer",
    "id": "123456789",
    "username": "@kesha",
    "price": "199",
    "predmetname": "iPhone 15"
  }'

Ответ (письмо принято в очередь и будет отправлено):

{ "id": "snd_ab12cd34", "status": "queued" }

Поле id сохраните — по нему можно узнать статус отправки (см. §3).

Дату в письмо (*DATE*) подставляем сами — в часовом поясе страны получателя. Тему, оформление, отправителя и способ доставки вы не задаёте. Очевидные опечатки домена исправляются автоматически (gamil.com → gmail.com).

3. Статус отправки

По id из ответа /send можно узнать, что стало с письмом (любые отправки этого токена — в т.ч. сделанные другими людьми с тем же токеном; чужие токены недоступны).

GET /api/v1/send/{id}
Authorization: Bearer <токен>

Ответ:

{ "id": "snd_ab12cd34", "status": "sent", "label": "Отправлено",
  "email": "b***@gmail.com", "country": "PL", "service": "myemail.pl",
  "created_at": "2026-10-28T10:00:00" }

`status`	`label`	Что значит
`pending`	В обработке	В очереди/отправляется — спросите позже
`sent`	Отправлено	Письмо ушло
`error`	Ошибка отправки	Не ушло; причина — в поле `error`

Неизвестный id или отправка под другим токеном → 404.
Адрес получателя в ответе замаскирован (b***@gmail.com).

Опционально — лента последних отправок/ошибок (нужен scope logs:read): GET /api/logs/sends и GET /api/logs/errors (параметр ?limit=, свежие сверху, email замаскирован).

4. Повторы на тот же адрес

Защита от дублей управляется на нашей стороне — никаких заголовков от вас не требуется. Если политика включена, повторная отправка на тот же адрес не выполняется: ответ 200 с {"status":"duplicate"} (письмо не отправлено).

5. Коды ответов

Код	Значение
`200`	Принято в очередь (`{"id":…, "status":"queued"}`)
`401`	Нет/неверный заголовок `Authorization`
`403`	Токен недействителен/отозван, либо сервис/домен ссылки не разрешён токену, либо запрос не с разрешённого IP
`404`	Статус: неизвестный `id` или отправка под другим токеном
`409`	Адрес в стоп-листе (отписка/жалоба) — отправка не выполняется
`422`	Ошибка данных: неизвестная страна/сервис, кривой e-mail, ссылка не `http(s)`
`429`	Превышен лимит запросов в минуту или суточная квота
`503`	Сервис недоступен (техработы или очередь переполнена) — повторите позже

6. Лимиты

На токен действуют лимит запросов в минуту и суточная квота (значения сообщим при выдаче) — они общие на весь токен, их делят все, кто им пользуется. При превышении — 429, повторите позже.
Отправка на адреса из нашего стоп-листа (отписки/жалобы) не выполняется (409).
Повтор на тот же адрес может быть отклонён (200 с status: duplicate) — см. §4.

7. Чего API не делает

Не принимает произвольный HTML/тему/отправителя — контент письма задаём мы.
Не раскрывает внутренние данные (какой сервер/ящик использован, чужие логи).
Не управляет токенами и настройками — только запуск отправки.