Пакетная отправка

POST /v1/emails/batch
Authorization: Bearer mi_live_…
Content-Type: application/json

До 100 писем за один HTTP-запрос. Параметры каждого письма — те же, что в POST /v1/emails. Письма обрабатываются независимо.

Пример

cURL

curl -X POST https://api.mailinfra.ru/v1/emails/batch \
  -H "Authorization: Bearer mi_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "from": "no-reply@ваш-домен.ru",
        "to": ["ivan@example.com"],
        "template": "welcome",
        "variables": { "user_name": "Иван" }
      },
      {
        "from": "no-reply@ваш-домен.ru",
        "to": ["maria@example.com"],
        "template": "welcome",
        "variables": { "user_name": "Мария" }
      }
    ]
  }'

Python

import httpx

users = [
    {"email": "ivan@example.com", "name": "Иван"},
    {"email": "maria@example.com", "name": "Мария"},
]

r = httpx.post(
    "https://api.mailinfra.ru/v1/emails/batch",
    headers={"Authorization": "Bearer mi_live_xxxxxxxx"},
    json={
        "emails": [
            {
                "from": "no-reply@ваш-домен.ru",
                "to": [u["email"]],
                "template": "welcome",
                "variables": {"user_name": u["name"]},
            }
            for u in users
        ]
    },
)
r.raise_for_status()
for result in r.json()["data"]["results"]:
    if result["error"]:
        print(f"#{result['index']} rejected: {result['error']['code']}")
    else:
        print(f"#{result['index']} accepted: {result['id']} {result['status']}")

TypeScript

const users = [
  { email: "ivan@example.com", name: "Иван" },
  { email: "maria@example.com", name: "Мария" },
];

const res = await fetch("https://api.mailinfra.ru/v1/emails/batch", {
  method: "POST",
  headers: {
    Authorization: "Bearer mi_live_xxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    emails: users.map((u) => ({
      from: "no-reply@ваш-домен.ru",
      to: [u.email],
      template: "welcome",
      variables: { user_name: u.name },
    })),
  }),
});

const { data } = await res.json();
data.results.forEach((result) => {
  if (result.error) {
    console.error(`#${result.index} rejected`, result.error.code);
  } else {
    console.log(`#${result.index} accepted`, result.id, result.status);
  }
});

Ответ

{
  "data": {
    "results": [
      {
        "index": 0,
        "id": "018e1b7a-1111-7000-aaaa-000000000001",
        "status": "QUEUED",
        "skipped_recipients": [],
        "error": null
      },
      {
        "index": 1,
        "id": null,
        "status": null,
        "skipped_recipients": [],
        "error": {
          "status_code": 404,
          "code": "not_found",
          "message": "Template 'missing-template' not found",
          "details": {}
        }
      }
    ],
    "accepted_count": 1,
    "failed_count": 1
  }
}

202 Accepted означает, что batch обработан, но не гарантирует успех каждого письма. Всегда проверяйте error у каждого результата. Поле index соответствует позиции письма во входном массиве; результаты возвращаются в том же порядке.

У успешного результата заполнены id и status, а error равен null. У отклонённого результата id и status равны null, а error содержит HTTP-статус и стандартную ошибку именно этого элемента.

Особенности

• Частичный успех: ожидаемая ошибка одного письма (например, шаблон не найден) не отменяет уже принятые письма и не останавливает следующие.
• Если невалидна сама структура batch (emails пуст, больше 100 элементов или поле письма не прошло проверку схемы), весь запрос отклоняется с 422 до начала обработки.
• Неожиданная серверная ошибка возвращается как 5xx. Поскольку batch неатомарный, ранее обработанные элементы к этому моменту уже могут быть приняты.
• Idempotency-Key не поддерживается для batch. Если нужна идемпотентность — отправляйте по одному.
• Лимит — 100 писем на запрос. Это технический лимит на HTTP-payload, не маркетинговая рассылка.