Типизированные SDK
API в виде типизированных методов.
@openemail/sdk представляет собой TypeScript-клиент без зависимостей для OpenEmail API, который сверяется с его документом OpenAPI при каждой сборке.
Коротко
Что такое SDK?
SDK (software development kit, набор средств разработки) оборачивает HTTP API в функции и типы одного языка. Вы вызываете методы, а не собираете запросы, и редактор проверяет аргументы ещё до отправки.
0
Зависимости в рантайме
30с
Таймаут на попытку
2
Повторы для повторяемых вызовов
Как это работает
Сверяется с API при каждой сборке
Проверка паритета читает документ OpenAPI и проваливает сборку при расхождении: отсутствующий метод, метод без операции или неверная область доступа.
Страницы без цикла по курсору
iterate() идёт по курсору и запрашивает каждую страницу, только когда до неё дойдёт ваш цикл, поэтому break останавливает запросы.
Повторы, которые не отправят дважды
Повторяемые вызовы получают до двух повторов с нарастающей паузой. Отправка использует во всех попытках один ключ идемпотентности, поэтому повтор возвращает исходное письмо.
Отправьте первое письмо
Установите его командой bun add @openemail/sdk и задайте в OPENEMAIL_API_KEY ключ из раздела «Настройки», «API-ключи».
import { init, openemail } from '@openemail/sdk' init({ apiKey: process.env.OPENEMAIL_API_KEY }) const email = await openemail.emails.send({ from: 'Acme Billing <[email protected]>', to: '[email protected]', subject: 'Your September invoice', html: '<p>Invoice attached.</p>',}) console.log(email.id, email.status)Что вы получаете
Уже в продукте
Node, Bun и Deno
Node 20 и новее, ESM или CommonJS, а ещё он принимает ваш собственный fetch.
Ранняя проверка ключей
Ключ с неверным префиксом выбрасывает ошибку при создании клиента, а не в виде 401.
Один клиент, много рабочих пространств
Передайте apiKey в вызов, чтобы работать в другом рабочем пространстве.
Ошибки для ветвления
OpenEmailApiError содержит status, code и requestId, а также isRateLimited и isNotFound.
Советы
Как извлечь максимум
- 01
Ключ в переменной окружения
Задайте OPENEMAIL_API_KEY, и общий клиент прочитает его сам, так что ключ не окажется в исходном коде.
- 02
Создайте один клиент
Создайте клиент один раз, в отдельном модуле, и импортируйте его в остальных местах.
- 03
Проверяйте статус
Даже выполненная отправка может оказаться в очереди, запланированной или неудачной, поэтому проверьте status, прежде чем считать письмо доставленным.
Положение дел
Полезно знать
- Автоматизация релизов
- Публикация ручная, поэтому версия попадает в npm, когда её кто-то запустит, а не когда изменение вливается.
- Другие языки
- Только TypeScript. Клиентов для Python, Go или Ruby пока нет.
Вопросы
Часто спрашивают
Что дальше
Хорошо сочетается с
Начать
Ваш домен,
ваша почта.
Направьте домен на OpenEmail и читайте его почту в ящике, построенном вокруг него. Бесплатный тариф включает один домен.
