Подключить

Для интеграторов

Пакетная отправка больших списков

Нужно принять сотни тысяч адресов из своей платформы и отдать их транспорту пакетами, не упираясь в лимиты новой рассылки.

Лимиты из спецификации

ЛимитЗначениеПри превышении
Частота запросов10 000 в минутуHTTP 429, reason request_throttled
Отправка для новой рассылки100 писем за 5 минут450 ratelimit exceeded / send_rate_limited
Создание пакетов40 пакетов за 5 минутошибка E429
Размер письма50 МБотказ на приёме

Числа — боевые лимиты из спецификации; при превышении смотрите reason в ответе.

Метод

POST https://api.samotpravil.ru/api/v1/add_json_package (operationId: post_v1_add_json_package). Заголовок Authorization: <ключ> без префикса.

Обязательные поля тела: email_from, name_from, subject, message_text, массив users (у получателя — emailto). Опционально: external_id (приходит в вебхуках), трекинг, стоп-листы, заголовки.

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

curl -sS -X POST 'https://api.samotpravil.ru/api/v1/add_json_package' \
  -H 'Authorization: <ключ>' \
  -H 'Content-Type: text/plain' \
  --data-binary @- <<'JSON'
{
  "email_from": "info@domain.ru",
  "name_from": "Domain",
  "subject": "Привет {{ name }}",
  "check_global_stop_list": true,
  "message_text": "<html><p>Здравствуйте, {{ name }}!</p></html>",
  "track_open": true,
  "track_click": true,
  "external_id": "seg-1776755427",
  "users": [
    { "emailto": "to1@domain.com", "name": "Вася" },
    { "emailto": "to2@domain.com", "name": "Петя" }
  ]
}
JSON

Тело в коллекции/спеке часто уходит как text/plain с JSON внутри — так же ходит исторический клиент. Node-пакет шлёт JSON-объект тем же путём.

Нарезка на стороне клиента

Для «полмиллиона» адресов режьте users кусками до 100 (лимит новой рассылки) и не чаще 40 пакетов за 5 минут (ориентир паузы между пакетами ~7,5 с). В Node:

import { Samotpravil } from "samotpravil";

const client = new Samotpravil({ apiKey: process.env.SAMOTPRAVIL_API_KEY });
const { packs, packIds } = await client.sendPackages({
  email_from: "info@domain.ru",
  name_from: "Domain",
  subject: "Рассылка",
  message_text: "<p>Текст</p>",
  users: hugeList, // [{ emailto, name?, ... }]
  chunkSize: 100,
  delayMs: 7500,
});

Повторы при 429 / rate-limit — с задержкой из ответа, не в тесном цикле.

Статусы пакета

Вебхуки пакетной отправки приходят в поле xml_messages (не messages). До 100 объектов в одном вызове. См. приём статусов доставки.

Бесплатного тестового ключа нет (#21204). Регистрация в личном кабинете, верификация домена отправителя (DNS), затем боевой ключ для api.samotpravil.ru.

Дальше: