ドキュメント本文へスキップ
SDK

設定

クライアントを作る 3 つの方法、すべてのオプション、そしてリクエスト送信前に拒否されるもの。

オプション

openemail.ts
import OpenEmail, { createOpenEmail, init, openemail } from '@openemail/sdk' init({ apiKey: process.env.OPENEMAIL_API_KEY })await openemail.me.ping() export const billing = createOpenEmail({ apiKey: process.env.BILLING_API_KEY! }) const pinned = new OpenEmail({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk' }) const quick = new OpenEmail('oe_live_…')
エントリーポイント得られるもの
`init(options)`共有クライアントを設定して返します。以後 openemail はどのモジュールでもそのクライアントになり、省略したものは環境変数から読まれます。
`openemail`共有クライアント。init より前に使うと、最初の呼び出し時に OPENEMAIL_API_KEY と OPENEMAIL_BASE_URL から自分を組み立てます。
`createOpenEmail(options)`同じ環境変数フォールバックを持つ別のクライアント。共有クライアントの隣でもう 1 つのキーを使うときや、自分のモジュールがエクスポートするインスタンスを作るときに使います。createClient は envless SDK が使う名前による同じ関数です。
`new OpenEmail(options)` または `new OpenEmail(apiKey)`渡したものだけから作られる別のクライアント。環境変数は読まないので apiKey が必須です。デフォルトエクスポートでもあります。
options.ts
init({  apiKey: 'oe_live_…',  baseUrl: 'https://api.openemail.uk',  timeoutMs: 30_000,  maxRetries: 2,  fetch: myFetch,  headers: {},  userAgent: 'billing-service/1.4',  disableUpdateNotice: true,})
オプション既定値補足
`apiKey`OPENEMAIL_API_KEYinit と createOpenEmail が環境変数から読みます。oe_live_ または oe_test_ で始まる必要があります。
`baseUrl`https://api.openemail.ukまたは OPENEMAIL_BASE_URL。末尾のスラッシュは取り除かれ、init と createOpenEmail はホスト名だけの値には https:// を、localhost には http:// を前置します。
`timeoutMs`30000呼び出し単位ではなく試行単位です。ヘッダーだけでなくボディの読み取りも対象になります。0 で無効化されます。
`maxRetries`2繰り返しても安全な呼び出しについて、初回のあとの追加試行回数です。呼び出しごとではなくクライアントに設定します。
`fetch`グローバルのものバインド済みです。プロキシ、Worker のバインディング、テスト用のダブルを使うときに渡してください。
`headers`{}すべてのリクエストに付与されます。
`userAgent`openemail-sdk/<version>設定を許可しないブラウザーを除く、すべてのランタイムから送られます。
`disableUpdateNotice`falsenpm 上の新しいバージョンをプロセスごとに 1 回確認する処理を省きます。確認は出力がターミナルに向いているときだけ走り、OPENEMAIL_DISABLE_UPDATE_NOTICE でも無効にできます。
`dangerouslyAllowBrowser`falsewindow と document が存在する場所でもクライアントを起動できるようにします。ページ用ではなく、それらを定義するテストハーネス用です。

送信前に拒否されるもの

これらは、最初の送信時に分かりにくい失敗として表面化するのではなく、誤った値を書いたその行からプレーンな Error を投げます。メッセージには何が誤っていて、代わりに何を渡すべきかが書かれています。

拒否される条件理由
キーがまったくないapiKey も OPENEMAIL_API_KEY も設定されておらず、認証に使えるものがありません。
セッションクッキーまたはセッショントークンここで認証できるのは oe_live_ と oe_test_ だけで、API 側も同じことを言います。チェックは接頭辞だけなので、失効したキーは通信時に失敗します。
http でも https でもない `baseUrl`それ以外は fetch できず、検証しないままだと、まったく別の場所から生の TypeError として後で失敗します。
ブラウザーキーが devtools を開いた人すべてに読まれてしまいます。下のセクションを参照してください。
`fetch` がどこにもないfetch として渡すか、Node 20+ で実行してください。
どのメソッドでも空、またはドットだけの idメソッド呼び出し時に投げられます。ドットだけのパスセグメントはどの URL パーサーでも除去されるため、リクエストが別のエンドポイントに届いてしまいます。

testMode オプションはありませんし、今後も作られません。キーのスキーム自体がヒントではなく認証情報の一部なので、モードはキーの性質です。openemail.mode は接頭辞を読むだけで、何も決めません。

1 つのクライアント、複数のキー

クライアントは一度作って共有してください。リクエストごとに新しいインスタンスを作るのは、fetch のバインドと設定を無駄に捨てる行為であり、そこに載っている状態はどれも呼び出し元ごとのものではありません。

複数のワークスペースを代行して送信するジョブなど、そうしなければキーごとに 1 インスタンスを強いられる場合には、apiKey を呼び出しに渡してください。そのリクエストに限って Authorization ヘッダーを差し替え、クライアントには何も残しません。

per-call-key.ts
await openemail.emails.send(message) await openemail.emails.send(message, { apiKey: workspace.apiKey }) await openemail.threads.list({ folder: 'inbox', apiKey: workspace.apiKey })await openemail.webhooks.list({ apiKey: workspace.apiKey })

tempMail 以外のすべてのメソッドが、最後の引数で signal と並べてこれを受け取ります。一覧系ではフィルターと同じオブジェクトです。コンストラクターと同じ規則でリクエスト送信前に検査されるので、タイプミスは、後から探しに行かなければならない認証情報についての 401 ではなく、{ apiKey } on this call を名指しする Error になります。再試行された呼び出しは、渡されたキーを保持します。

signal は AbortSignal です。中断するとリクエストが止まり、その後ろで待っている再試行も止まります。

openemail.mode はクライアントが構築されたときのキーを表し、上書きには追随しません。1 つのクライアントが複数のキーを扱うようになれば、報告すべき単一のモードは存在しないので、渡したキーから読み取ってください。

ブラウザーから使う場合

クライアントはブラウザーでの起動を拒み、リクエストが出る前に例外を投げます。ページに置いたキーは公開したキーです。devtools を開いた人は誰でも、それでメールを送り、メールボックスを読めます。代わりにサーバー、サーバーレス関数、スクリプトから呼び出してください。

使い捨て受信箱だけは例外です。createTempMail() は API キーを持たないクライアントを作るので、ページ内でも安全です。匿名で受信箱を作り、読み取りのたびに create が返したトークンを、呼び出しごとの inboxToken として、あるいは一度だけ createTempMail({ inboxToken }) として送ります。

temp-mail.ts
import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })

それでも dangerouslyAllowBrowser: true を渡す場合、API は CORS プリフライトで Content-Type、Authorization、Idempotency-Key のみを許可します。そのため headers に余分なヘッダーを入れると、リクエストではなくプリフライトが失敗し、それについてブラウザーが報告する内容は何の役にも立ちません。