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

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

Возвращает 202 Accepted и присвоенный id ещё до фактической доставки. Итоговый статус приходит через вебхуки или его можно запросить по id.

Минимальный пример

cURL

curl -X POST https://api.mailinfra.ru/v1/emails \
  -H "Authorization: Bearer mi_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@ваш-домен.ru",
    "to": ["user@example.com"],
    "subject": "Добро пожаловать!",
    "html": "<p>Привет!</p>",
    "text": "Привет!"
  }'

Python

import httpx

r = httpx.post(
    "https://api.mailinfra.ru/v1/emails",
    headers={"Authorization": "Bearer mi_live_xxxxxxxx"},
    json={
        "from": "hello@ваш-домен.ru",
        "to": ["user@example.com"],
        "subject": "Добро пожаловать!",
        "html": "<p>Привет!</p>",
        "text": "Привет!",
    },
)
r.raise_for_status()
print(r.json()["data"]["id"])

TypeScript

const res = await fetch("https://api.mailinfra.ru/v1/emails", {
  method: "POST",
  headers: {
    Authorization: "Bearer mi_live_xxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "hello@ваш-домен.ru",
    to: ["user@example.com"],
    subject: "Добро пожаловать!",
    html: "<p>Привет!</p>",
    text: "Привет!",
  }),
});
const { data } = await res.json();
console.log(data.id);

Go

body := strings.NewReader(`{
  "from": "hello@ваш-домен.ru",
  "to": ["user@example.com"],
  "subject": "Добро пожаловать!",
  "html": "<p>Привет!</p>"
}`)

req, _ := http.NewRequest("POST", "https://api.mailinfra.ru/v1/emails", body)
req.Header.Set("Authorization", "Bearer mi_live_xxxxxxxx")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Ответ:

{
  "data": {
    "id": "018e1b7a-1111-7000-aaaa-111111111111",
    "status": "QUEUED",
    "skipped_recipients": []
  }
}

Параметры запроса

Поле	Тип	Обязательно	Описание
from	string	да	Email отправителя. Домен должен быть верифицирован и привязан к проекту.
from_name	string	—	Отображаемое имя (до 200 символов). В клиенте: Имя <from>.
to	string[]	да	Получатели. Сумма to + cc + bcc ≤ 50.
cc	string[]	—	CC.
bcc	string[]	—	BCC.
reply_to	string[]	—	До 10 адресов.
subject	string	*	До 998 символов, без переводов строк.
html	string	*	HTML-тело письма.
text	string	*	Текстовая версия. Рекомендуется указывать вместе с html.
headers	object	—	Пользовательские заголовки (см. ниже).
tags	string[]	—	До 10 меток, каждая до 32 символов.
template	string	*	Slug шаблона.
variables	object	—	Переменные для рендера шаблона.
attachments	object[]	—	До 10 вложений в base64 (см. ниже).

* Без template обязательны subject и хотя бы одно из html / text. С template тема и тело берутся из шаблона.

Пользовательские заголовки

{
  "headers": {
    "X-Order-Id": "12345",
    "X-User-Id": "usr_abc"
  }
}

Нельзя переопределить системные заголовки: from, to, cc, bcc, reply-to, subject, message-id, date, dkim-signature, received, return-path и любые x-mailinfra-*.

Такой запрос отклоняется целиком с 422 reserved_email_header; заголовок не игнорируется молча:

{
  "error": {
    "code": "reserved_email_header",
    "message": "Системные заголовки письма нельзя переопределять.",
    "details": {
      "code": "reserved_email_header",
      "header": "From"
    }
  },
  "request_id": "…"
}

Значения пользовательских заголовков не могут содержать переводы строк (\r или \n). Это защищает письмо от header injection.

Вложения

Содержимое файла передаётся обычной base64-строкой без префикса data::

{
  "from": "hello@ваш-домен.ru",
  "to": ["user@example.com"],
  "subject": "Документы по заказу",
  "text": "Документы во вложении.",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "content_base64": "JVBERi0xLjQK…"
    }
  ]
}

Поле	Обязательно	Описание
filename	да	Отображаемое имя файла, до 255 символов. Пути удаляются.
content_type	—	MIME-тип; по умолчанию application/octet-stream.
content_base64	да	Байты файла в base64. Переносы MIME-base64 допустимы.

Ограничения: до 10 вложений, до 10 МиБ на файл и до 25 МиБ суммарно. Размер считается после декодирования base64. Невалидный base64 и превышение лимита отклоняют письмо до его создания.

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

POST /v1/emails
Idempotency-Key: order-12345-welcome

Повтор того же запроса с тем же ключом:

• 200 OK (вместо 202)
• заголовок Idempotent-Replayed: true
• тело идентично первому ответу, повторной отправки не происходит

Используйте, если вызываете API по сетевому таймауту — это безопаснее try/except с retry.

Пропущенные получатели

Адреса из списка подавления тихо исключаются:

{
  "data": {
    "id": "...",
    "status": "QUEUED",
    "skipped_recipients": [
      { "email": "blocked@example.com", "reason": "suppressed" }
    ]
  }
}

Если все получатели подавлены — письмо не создаётся, возвращается 422 с кодом all_recipients_suppressed.

Статусы письма

QUEUED → SENDING → SENT → DELIVERED
                       ↘ BOUNCED
                       ↘ COMPLAINED
             ↘ FAILED

Статус	Значение
QUEUED	Принято в очередь
SENDING	Передаётся в MTA
SENT	Передано SMTP-серверу получателя
DELIVERED	Получено получателем
BOUNCED	Недоставка
COMPLAINED	Жалоба на спам
FAILED	Внутренняя ошибка отправки
SIMULATED	TEST-ключ, реальной отправки не было

Click tracking

Если в проекте включён Click tracking, MailInfra перепишет абсолютные HTTP- и HTTPS-ссылки в HTML-теле письма и создаст событие clicked при переходе получателя.

Чтение письма и событий

GET /v1/emails
GET /v1/emails/{id}
GET /v1/emails/{id}/events

Доступно ключам с правом чтения (FULL_ACCESS, READ_ONLY). Реал-тайм без поллинга — через вебхуки.

Лимиты

Все лимиты — на странице Ошибки и лимиты →.