Документация Email API

API Rusender позволяет отправлять транзакционные письма — подтверждения заказов, восстановление пароля, уведомления — одним POST-запросом. Отправка выполняется через публичное API Rusender: вы авторизуетесь API-ключом и указываете, через какой ключ отправки уйдёт письмо.

Если вы уже отправляете письма через заголовок X-Api-Key — ваш способ продолжает работать. Рекомендуем перейти на новый механизм: см. раздел Миграция со старого способа.

Шаг 1. Создайте API-ключ

API-ключ — это ключ доступа к публичному API Rusender с настраиваемыми разрешениями (scopes).

В личном кабинете откройте Интеграции → API и нажмите «Создать API-ключ».
Укажите название и отметьте разрешение external_mail.send (отправка транзакционных писем).
Скопируйте токен вида rs_ck_v1_... — он показывается только один раз.

Подробнее о токенах, разрешениях и ротации — в статье Аутентификация.

Шаг 2. Создайте ключ отправки

Ключ отправки — это отправляющая сущность: связка верифицированного домена и репутации отправителя. Письмо всегда уходит через конкретный ключ отправки, его числовой ID (key_id) указывается прямо в URL запроса.

В личном кабинете откройте раздел Транзакционные отправки и нажмите «Создать ключ».
Укажите название и выберите верифицированный домен.
ID ключа виден на его карточке, либо получите список ключей запросом GET /api/v1/public/external-mails/keys (требуется разрешение external_mail.read).

Обратите внимание: сразу после создания ключ отправки не активен — для активации обратитесь в поддержку.

Важно: адрес в from.email должен принадлежать домену ключа отправки, иначе API вернёт 404. Подробнее — в статье Ключи отправки.

Шаг 3. Отправьте письмо

POST `/api/v1/external-mails/send/{key_id}`

В заголовке Authorization передайте токен API-ключа: Authorization: Bearer rs_ck_v1_...

Пример тела запроса

{
  "idempotencyKey": "order-12345-confirmation",
  "mail": {
    "to": { "email": "user@example.com", "name": "Иван" },
    "from": { "email": "noreply@yourdomain.ru", "name": "MyApp" },
    "subject": "Подтверждение заказа",
    "html": "<h1>Спасибо за заказ!</h1>"
  }
}

Важно: тестовые письма отправляйте только на существующие адреса — отправка на несуществующие ящики портит репутацию ключа вплоть до блокировки.

Поля запроса

Поле	Тип	Обязательное	Описание
`mail.to.email`	string	да	Адрес получателя
`mail.to.name`	string	нет	Имя получателя
`mail.from.email`	string	да	Адрес отправителя на домене ключа отправки
`mail.from.name`	string	нет	Имя отправителя
`mail.subject`	string ≤ 255	да	Тема письма
`mail.html` / `mail.text`	string	хотя бы одно	Содержимое письма
`mail.previewTitle`	string ≤ 255	нет	Прехедер (текст превью)
`mail.cc`, `mail.bcc`	string ≤ 255	нет	Копия и скрытая копия, адреса через запятую
`mail.headers`	object	нет	Кастомные заголовки `X-*`
`mail.attachments`	array ≤ 20	нет	Вложения `{ "имя_файла": "base64" }`, см. Вложения и заголовки
`idempotencyKey`	string ≤ 150	нет, рекомендуется	Ключ идемпотентности

Отправка по шаблону

Чтобы отправить письмо по шаблону, созданному в Rusender, используйте эндпоинт:

POST `/api/v1/external-mails/send-by-template/{key_id}`

Вместо html/text передайте в mail поля idTemplateMailUser (ID шаблона) и params (объект подстановок для переменных шаблона). Остальные поля и авторизация — те же.

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

Передавайте собственный idempotencyKey в каждом запросе — это гарантирует, что при повторе запроса (таймаут, ретрай) письмо не будет отправлено дважды. Без ключа сервер применяет автоматическую защиту от дублей, но она не гарантирует отсутствие пропущенных или лишних отправок, а в ответе вернётся warning.

Ответы сервера

Успешный ответ — 200 OK:

{ "uuid": "018e1234-abcd-7000-8000-000000000001" }

По uuid можно отслеживать статус письма. Возможные ошибки:

Код	Когда возникает
400	Невалидное тело запроса или проблема с вложениями (запрещённый тип, превышен размер)
401	Невалидный или отозванный токен API-ключа
402	Недостаточно средств / исчерпан лимит писем тарифа
403	У API-ключа нет разрешения `external_mail.send`, ключ отправки недоступен или не активен
404	Ключ отправки или домен отправителя не найден; для шаблонной отправки — не найден шаблон
422	Получатель отписался, жаловался на письма или адрес недоступен (bounce)
429	Превышен лимит запросов; повторите после `Retry-After`
503	Сервис временно недоступен, повторите позже

Тело ошибки содержит машиночитаемый код и описание. Полный справочник — в API Reference.

Примеры кода

cURL

curl -X POST "https://api.rusender.ru/api/v1/external-mails/send/42" \
  -H "Authorization: Bearer $RUSENDER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "order-12345-confirmation",
    "mail": {
      "to": { "email": "user@example.com", "name": "Иван" },
      "from": { "email": "noreply@yourdomain.ru", "name": "MyApp" },
      "subject": "Подтверждение заказа",
      "html": "<h1>Спасибо за заказ!</h1>"
    }
  }'

PHP

$keyId = 42;
$payload = [
    'idempotencyKey' => 'order-12345-confirmation',
    'mail' => [
        'to' => ['email' => 'user@example.com', 'name' => 'Иван'],
        'from' => ['email' => 'noreply@yourdomain.ru', 'name' => 'MyApp'],
        'subject' => 'Подтверждение заказа',
        'html' => '<h1>Спасибо за заказ!</h1>',
    ],
];

$ch = curl_init("https://api.rusender.ru/api/v1/external-mails/send/{$keyId}");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RUSENDER_API_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
echo $response; // {"uuid":"018e1234-..."}

Python

import os
import requests

key_id = 42
response = requests.post(
    f"https://api.rusender.ru/api/v1/external-mails/send/{key_id}",
    headers={"Authorization": f"Bearer {os.environ['RUSENDER_API_TOKEN']}"},
    json={
        "idempotencyKey": "order-12345-confirmation",
        "mail": {
            "to": {"email": "user@example.com", "name": "Иван"},
            "from": {"email": "noreply@yourdomain.ru", "name": "MyApp"},
            "subject": "Подтверждение заказа",
            "html": "<h1>Спасибо за заказ!</h1>",
        },
    },
)
print(response.json())  # {'uuid': '018e1234-...'}

Node.js

const keyId = 42;

const response = await fetch(`https://api.rusender.ru/api/v1/external-mails/send/${keyId}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RUSENDER_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    idempotencyKey: 'order-12345-confirmation',
    mail: {
      to: { email: 'user@example.com', name: 'Иван' },
      from: { email: 'noreply@yourdomain.ru', name: 'MyApp' },
      subject: 'Подтверждение заказа',
      html: '<h1>Спасибо за заказ!</h1>',
    },
  }),
});

console.log(await response.json()); // { uuid: '018e1234-...' }

JavaScript (браузер)

Не используйте API-ключ в браузерном коде — токен станет доступен любому посетителю страницы. Отправляйте письма только с сервера; пример выше для Node.js подходит без изменений и для других серверных JS-сред.

Ограничения

Тело запроса — до 5 МБ; вложения — до 15 МБ суммарно, не более 20 файлов. Исполняемые файлы, архивы и системные файлы запрещены.
Лимит запросов к публичному API — 300 запросов в минуту на API-ключ (см. заголовки X-RateLimit-* в ответе).
Кодировка запроса — UTF-8.

Миграция со старого способа

Раньше отправка выполнялась с JWT-токеном в заголовке X-Api-Key, а токен был жёстко привязан к одному ключу (в старой терминологии он назывался «API ключ», теперь это «Ключ отправки»). Старый способ продолжает работать, существующие токены остаются валидными — но новые возможности публичного API доступны только с новыми API-ключами.

	Старый способ	Новый способ
Заголовок	`X-Api-Key: <JWT>`	`Authorization: Bearer rs_ck_v1_...`
URL отправки	`/api/v1/external-mails/send`	`/api/v1/external-mails/send/{key_id}`
Привязка	1 токен = 1 ключ отправки	1 API-ключ → любой ключ отправки аккаунта
Права	Полный доступ	Разрешения (scopes)
Ротация секрета	Только пересоздание	Ротация с переходным периодом 24 часа
Остальное API (контакты, шаблоны, статистика)	Недоступно	Доступно тем же ключом

Шаги перехода:

Создайте API-ключ с разрешением external_mail.send (Интеграции → API).
Узнайте ID своего ключа отправки (карточка ключа в разделе Транзакционные отправки).
В интеграции замените заголовок X-Api-Key: <JWT> на Authorization: Bearer <токен> и добавьте /{key_id} в конец URL отправки.
Формат тела запроса и ответа не изменился — больше ничего менять не нужно.

Дата публикации: 2 сентября 2025 Обновлено: 19 июня 2026

Автор статьи

Дарья Л.

Написано статей: 117

Контент-менеджер и email маркетолог в RuSender.

Поделиться статьёй