型付きSDK
API を、型付きのメソッドで。
@openemail/sdk は OpenEmail API 用の依存関係ゼロの TypeScript クライアントで、ビルドのたびに API の OpenAPI ドキュメントと照合されます。
概要
SDK とは？
SDK（ソフトウェア開発キット）は、HTTP API をひとつの言語の関数と型で包んだものです。リクエストを組み立てる代わりにメソッドを呼び出し、送信前にエディターが引数をチェックします。
0
ランタイム依存関係
30秒
試行ごとのタイムアウト
2
再実行可能な呼び出しの再試行
仕組み
ビルドのたびに API と照合
一致チェックが OpenAPI ドキュメントを読み、ずれがあればビルドを失敗させます。メソッドの欠落、オペレーションのないメソッド、誤ったスコープが対象です。
カーソルのループなしでページ送り
iterate() はカーソルをたどり、ループが到達したときにだけ各ページを取得します。break すればリクエストも止まります。
二重送信しない再試行
再実行可能な呼び出しは、間隔を空けながら最大 2 回まで再試行されます。送信ではすべての試行で同じ冪等キーを使うため、再試行しても元のメッセージが返ります。
最初のメールを送る
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 ではなく生成時に例外を投げます。
1 つのクライアントで複数のワークスペース
1 回の呼び出しに apiKey を渡せば、別のワークスペースとして操作できます。
分岐に使えるエラー
OpenEmailApiError は status、code、requestId に加え、isRateLimited と isNotFound を持ちます。
上手な使い方
使いこなすために
- 01
キーは環境変数に
OPENEMAIL_API_KEY を設定して共有クライアントに読ませれば、ソースにキーが残りません。
- 02
クライアントは 1 つだけ
クライアントは専用のモジュールで一度だけ作成し、ほかの場所ではそれを import します。
- 03
ステータスを確認
resolve した送信でも、送信待ち、予約済み、失敗のいずれかの場合があるため、配信済みとみなす前に status を確認してください。
現状
知っておきたいこと
- リリースの自動化
- 公開は手動のため、npm にバージョンが出るのは変更が入った時ではなく、誰かが実行した時です。
- 他の言語
- TypeScript のみです。Python、Go、Ruby のクライアントはまだありません。
質問
よくある質問
さらに見る
