Справочник API

Полный список эндпоинтов Public API — того, что доступно по API-ключу проекта. Страница собрана из OpenAPI-спеки, из которой генерятся и официальные SDK, поэтому разойтись с реальным поведением API она не может.

Машиночитаемая спека: mailinfra-public.json.

Основы

• База API — https://app.mailinfra.ru/v1.
• Аутентификация — Authorization: Bearer mi_live_… (рабочие отправки) или Bearer mi_test_… (sandbox: письмо сохраняется со статусом SIMULATED, не доставляется и не расходует месячный объём).
• Успешный ответ всегда приходит конвертом {"data": …}.
• Ошибка — конвертом {"error": {"code", "message", "details"}, "request_id"}. Ветвитесь по error.code, а не по тексту сообщения: коды и лимиты.
• X-Request-ID есть в каждом ответе — именно его называйте в обращении в поддержку.

Не собирайте запросы руками

Идемпотентность, повторы с backoff и разбор ошибок уже сделаны в официальных SDK: Python, Node.js, PHP, Go.

Эндпоинты

GET /emails

Параметры

Параметр	Где	Тип	Обязательно	Описание
status	query	EmailStatus | null	нет
from_email	query	string | null	нет
to_email	query	string | null	нет
tag	query	string | null	нет
from	query	string (ISO-8601) | null	нет
to	query	string (ISO-8601) | null	нет
limit	query	integer	нет	от 1, до 100, по умолчанию 25

Ответ

Поле data — список EmailListItem.

Коды ответа

Код	Когда	Заголовки
200	Успешный ответ	X-Request-ID
429	Превышен лимит: RPS ключа (error.code = rps_exceeded), месячный объём плана или дневной потолок организации. Заголовок Retry-After содержит задержку до повтора.	Retry-After, X-Request-ID
прочие	Ошибка. Единый конверт: error.code, error.message, error.details, request_id	X-Request-ID

POST /emails

Параметры

Параметр	Где	Тип	Обязательно	Описание
Idempotency-Key	заголовок	string | null	нет	до 255 символов

Тело запроса

Схема: EmailSendRequest.

Поле	Тип	Обязательно	Описание
attachments	array<EmailAttachmentInput>	нет	до 10 элементов
bcc	array<string (email)>	нет	до 50 элементов
cc	array<string (email)>	нет	до 50 элементов
from	string (email)	да
from_name	string | null	нет	до 200 символов
headers	object<string, string>	нет
html	string | null	нет
reply_to	array<string (email)>	нет	до 10 элементов
subject	string | null	нет	до 998 символов
tags	array<string>	нет	до 10 элементов
template	string | null	нет	до 100 символов
text	string | null	нет
to	array<string (email)>	да	не пустой список, до 50 элементов
variables	object<string, any>	нет

Ответ

Поле data — EmailSendResponseData.

Коды ответа

Код	Когда	Заголовки
200	Идемпотентный повтор: запрос с таким Idempotency-Key уже был принят, письмо повторно не отправлено.	Idempotent-Replayed, X-Request-ID
202	Успешный ответ	X-Request-ID
429	Превышен лимит: RPS ключа (error.code = rps_exceeded), месячный объём плана или дневной потолок организации. Заголовок Retry-After содержит задержку до повтора.	Retry-After, X-Request-ID
прочие	Ошибка. Единый конверт: error.code, error.message, error.details, request_id	X-Request-ID

POST /emails/batch

Тело запроса

Схема: BatchSendRequest.

Поле	Тип	Обязательно	Описание
emails	array<EmailSendRequest>	да	не пустой список, до 100 элементов

Ответ

Поле data — BatchSendResponseData.

Коды ответа

Код	Когда	Заголовки
202	Успешный ответ	X-Request-ID
429	Превышен лимит: RPS ключа (error.code = rps_exceeded), месячный объём плана или дневной потолок организации. Заголовок Retry-After содержит задержку до повтора.	Retry-After, X-Request-ID
прочие	Ошибка. Единый конверт: error.code, error.message, error.details, request_id	X-Request-ID

GET /emails/{email_id}

Параметры

Параметр	Где	Тип	Обязательно	Описание
email_id	путь	string (uuid)	да

Ответ

Поле data — EmailDetail.

Коды ответа

Код	Когда	Заголовки
200	Успешный ответ	X-Request-ID
429	Превышен лимит: RPS ключа (error.code = rps_exceeded), месячный объём плана или дневной потолок организации. Заголовок Retry-After содержит задержку до повтора.	Retry-After, X-Request-ID
прочие	Ошибка. Единый конверт: error.code, error.message, error.details, request_id	X-Request-ID

GET /emails/{email_id}/events

Параметры

Параметр	Где	Тип	Обязательно	Описание
email_id	путь	string (uuid)	да

Ответ

Поле data — список EmailEventPublic.

Коды ответа

Код	Когда	Заголовки
200	Успешный ответ	X-Request-ID
429	Превышен лимит: RPS ключа (error.code = rps_exceeded), месячный объём плана или дневной потолок организации. Заголовок Retry-After содержит задержку до повтора.	Retry-After, X-Request-ID
прочие	Ошибка. Единый конверт: error.code, error.message, error.details, request_id	X-Request-ID

Схемы

BatchSendError

Поле	Тип	Обязательно	Описание
code	string	да
details	object<string, any>	нет
message	string	да
status_code	integer	да

BatchSendRequest

Поле	Тип	Обязательно	Описание
emails	array<EmailSendRequest>	да	не пустой список, до 100 элементов

BatchSendResponseData

Поле	Тип	Обязательно	Описание
accepted_count	integer	да
failed_count	integer	да
results	array<BatchSendResult>	да

BatchSendResult

Поле	Тип	Обязательно	Описание
error	BatchSendError | null	нет
id	string (uuid) | null	нет
index	integer	да
skipped_recipients	array<object<string, string>>	нет
status	EmailStatus | null	нет

BounceCategory

Нормализованная причина bounce — для UI/Debug Explorer.

Отдельно от BounceType (hard/soft): категория даёт человекочитаемую причину, вычисляется классификатором по enhanced-коду/тексту диагностики. См.

Допустимые значения:

• invalid-recipient
• mailbox-full
• message-too-large
• content-spam-block
• policy-rejection
• reputation-blocklist
• greylisting
• dns-mx-failure
• connection-error
• rate-limited
• auth-failure
• unknown

BounceType

Допустимые значения:

• hard
• soft

DkimSigningStatus

Достоверность DKIM-подписи письма.

EXPECTED — на нашей стороне известно, что домен верифицирован и ключ для него существует, поэтому Haraka должна была подписать письмо. Это не подтверждение факта подписи — Haraka сегодня не сообщает результат подписания обратно. CONFIRMED/FAILED зарезервированы под будущий callback от Haraka (fast-follow), значения уже есть, миграция не нужна.

Допустимые значения:

• expected
• confirmed
• failed
• not_signed

EmailAttachmentInput

Вложение в исходящем письме.

content_base64 — содержимое файла в base64.

Поле	Тип	Обязательно	Описание
content_base64	string	да	до 14 348 938 символов
content_type	string	нет	до 255 символов, по умолчанию "application/octet-stream"
filename	string	да	не пустая строка, до 255 символов

EmailDetail

Поле	Тип	Обязательно	Описание
bcc_emails	array<string> | null	да
bounce_category	BounceCategory | null	нет
bounce_type	BounceType | null	нет
cc_emails	array<string> | null	да
created_at	string (ISO-8601)	да
delivered_at	string (ISO-8601) | null	да
dkim_aligned	boolean | null	нет
dkim_d	string | null	нет
dkim_selector	string | null	нет
dkim_signing_status	DkimSigningStatus | null	нет
dmarc_aligned	boolean | null	нет
failed_at	string (ISO-8601) | null	да
final_smtp_code	integer | null	нет
final_smtp_enhanced	string | null	нет
final_smtp_text	string | null	нет
from_email	string	да
from_name	string | null	да
headers	object<string, string>	да
html_body	string | null	да
id	string (uuid)	да
message_id	string | null	нет
project_id	string (uuid)	да
reply_to	array<string> | null	да
sent_at	string (ISO-8601) | null	да
source	EmailSource	нет	по умолчанию "API"
spf_aligned	boolean | null	нет
spf_authorized_ip	boolean | null	нет
spf_domain	string | null	нет
status	EmailStatus	да
subject	string	да
suppression_reason	SuppressionReason | null	нет
tags	array<string>	да
text_body	string | null	да
to_emails	array<string>	да

EmailEventPublic

Поле	Тип	Обязательно	Описание
data	object<string, any>	да
id	string (uuid)	да
ip_address	string | null	нет
timestamp	string (ISO-8601)	да
type	EmailEventType	да
user_agent	string | null	нет

EmailEventType

Допустимые значения:

• queued
• sending
• sent
• delivered
• smtp_connected
• opened
• clicked
• bounced
• complained
• failed
• simulated

EmailListItem

Сокращённая репрезентация для списка.

Поле	Тип	Обязательно	Описание
bounce_category	BounceCategory | null	нет
bounce_type	BounceType | null	нет
created_at	string (ISO-8601)	да
delivered_at	string (ISO-8601) | null	да
dkim_aligned	boolean | null	нет
dkim_d	string | null	нет
dkim_selector	string | null	нет
dkim_signing_status	DkimSigningStatus | null	нет
dmarc_aligned	boolean | null	нет
final_smtp_code	integer | null	нет
final_smtp_enhanced	string | null	нет
final_smtp_text	string | null	нет
from_email	string	да
id	string (uuid)	да
message_id	string | null	нет
project_id	string (uuid)	да
sent_at	string (ISO-8601) | null	да
source	EmailSource	нет	по умолчанию "API"
spf_aligned	boolean | null	нет
spf_authorized_ip	boolean | null	нет
spf_domain	string | null	нет
status	EmailStatus	да
subject	string	да
suppression_reason	SuppressionReason | null	нет
tags	array<string>	да
to_emails	array<string>	да

EmailSendRequest

POST /v1/emails.

Поле	Тип	Обязательно	Описание
attachments	array<EmailAttachmentInput>	нет	до 10 элементов
bcc	array<string (email)>	нет	до 50 элементов
cc	array<string (email)>	нет	до 50 элементов
from	string (email)	да
from_name	string | null	нет	до 200 символов
headers	object<string, string>	нет
html	string | null	нет
reply_to	array<string (email)>	нет	до 10 элементов
subject	string | null	нет	до 998 символов
tags	array<string>	нет	до 10 элементов
template	string | null	нет	до 100 символов
text	string | null	нет
to	array<string (email)>	да	не пустой список, до 50 элементов
variables	object<string, any>	нет

EmailSendResponseData

Поле	Тип	Обязательно	Описание
id	string (uuid)	да
skipped_recipients	array<object<string, string>>	нет
status	EmailStatus	да

EmailSource

Транспорт, через который письмо попало в пайплайн отправки.

Допустимые значения:

• API
• SMTP
• CAMPAIGN

EmailStatus

Допустимые значения:

• QUEUED
• SENDING
• SENT
• DELIVERED
• BOUNCED
• COMPLAINED
• FAILED
• SIMULATED

ErrorDetails

Поле	Тип	Обязательно	Описание
code	string	да
details	object<string, any> | null	нет
message	string	да

ErrorResponse

Единый конверт ошибки.

Ровно эта форма отдаётся всеми обработчиками исключений — доменными (MailInfraError), валидационными и fallback'ом на непойманное исключение. Схема подключена к OpenAPI через ERROR_RESPONSES, чтобы сгенерированные клиенты знали структуру ошибки, а не только её код.

Поле	Тип	Обязательно	Описание
error	ErrorDetails	да
request_id	string | null	нет

SuppressionReason

Допустимые значения:

• HARD_BOUNCE
• COMPLAINT
• UNSUBSCRIBE
• MANUAL