Официальные SDK

Язык	Пакет	Установка	Исходный код
Python 3.10+	mailinfra	pip install mailinfra	mailinfra-python
Node.js 20+ / TypeScript	mailinfra	npm install mailinfra	mailinfra-node
PHP 8.1+	mailinfra/mailinfra	composer require mailinfra/mailinfra	mailinfra-php
Go 1.22+	mailinfra-go	go get github.com/g7AzaZLO/mailinfra-go	mailinfra-go

Ошибки и предложения по SDK — в issues его репозитория.

Все четыре клиента ведут себя одинаково: одна политика повторов, одни коды ошибок, один алгоритм проверки подписи вебхуков. Отличается только синтаксис.

Что SDK делает за вас

Клиент — не просто обёртка над POST /v1/emails. В него зашито то, что иначе пришлось бы писать в каждом проекте заново:

• Идемпотентность. На каждую отправку ставится Idempotency-Key, и при повторе внутри того же вызова используется тот же ключ. Обрыв соединения или 503 не превращаются в два письма.
• Повторы. 429, 408, 425, 5xx и сетевые сбои повторяются с экспоненциальным backoff и половинным jitter. Неидемпотентные вызовы (пакетная отправка, отправка без ключа) повторяются только на 429 — там, где сервер заведомо ничего не принял.
• Rate limit. Заголовок Retry-After выполняется буквально. Если сервер просит ждать дольше минуты, SDK не блокирует ваш поток, а отдаёт ошибку с полем retry_after — решение остаётся за вами.
• Типизированные ошибки. error.code превращается в класс исключения (DomainNotVerifiedError, RateLimitError, UnprocessableError с разбором полей) или в часовую ошибку для errors.Is в Go. Незнакомый код не ломает клиент — он приходит как ошибка по HTTP-статусу.
• Типы. Модели Python и Node генерируются из OpenAPI-спеки MailInfra; модели PHP и Go написаны руками, но их состав сверяется с той же спекой автотестом. Разойтись с API они не могут.
• Локальная валидация. Лимиты получателей, тегов, темы и вложений проверяются до сетевого вызова: письмо с вложениями весит до 25 МиБ, и уезжать целиком ради 422 оно не должно.
• Вебхуки. Проверка HMAC-подписи с защитой от replay — одной функцией.

Что покрыто

SDK покрывают публичный API писем — всё, что доступно по API-ключу проекта:

Операция	Python	Node.js	PHP	Go
POST /v1/emails	emails.send	emails.send	emails->send	Emails.Send
POST /v1/emails/batch	emails.send_batch	emails.sendBatch	emails->sendBatch	Emails.SendBatch
GET /v1/emails/{id}	emails.get	emails.get	emails->get	Emails.Get
GET /v1/emails	emails.list	emails.list	emails->list	Emails.List
GET /v1/emails/{id}/events	emails.events	emails.events	emails->events	Emails.Events
Проверка подписи вебхука	webhooks.construct_event	webhooks.constructEvent	Webhooks::constructEvent	ConstructWebhookEvent

Полный список полей запроса и ответа — в справочнике API.

Управление доменами, шаблонами, списком подавления, вебхуками и API-ключами — это Management API: он работает по сессионному токену пользователя, а не по ключу проекта, поэтому в SDK пока не входит. Для автоматизации этих ресурсов обращайтесь к REST-эндпоинтам напрямую.

OpenAPI-спека

Машиночитаемое описание публичного API опубликовано здесь: mailinfra-public.json (та же спека лежит в resources/ каждого репозитория SDK). Она собирается из самого приложения, из неё генерируются типы SDK и справочник API, и CI не даёт ей разойтись с кодом.

Спека подходит и для генерации клиента под язык, которого пока нет среди официальных:

npx @openapitools/openapi-generator-cli generate \
  -i mailinfra-public.json -g <язык> -o ./mailinfra-client

Дальше

• Python SDK — быстрый старт и справочник.
• Node.js / TypeScript SDK — быстрый старт и справочник.
• PHP SDK — быстрый старт и справочник.
• Go SDK — быстрый старт и справочник.
• Переход с Resend
• Переход с SendGrid