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

Язык	Пакет	Установка
Python 3.10+	mailinfra	pip install mailinfra
Node.js 18+ / TypeScript	mailinfra	npm install mailinfra

Для PHP и Go официального пакета пока нет — используйте прямые HTTP-запросы, примеры есть в каждом разделе документации.

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

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

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

Что покрыто

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

Операция	Метод SDK
POST /v1/emails	emails.send
POST /v1/emails/batch	emails.send_batch / emails.sendBatch
GET /v1/emails/{id}	emails.get
GET /v1/emails	emails.list
GET /v1/emails/{id}/events	emails.events
Проверка подписи вебхука	webhooks.verify, webhooks.construct_event / constructEvent

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

OpenAPI-спека

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

# PHP
npx @openapitools/openapi-generator-cli generate \
  -i sdk/openapi/mailinfra-public.json -g php -o ./mailinfra-php

# Go
go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest \
  -package mailinfra sdk/openapi/mailinfra-public.json > mailinfra.go

Дальше

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