SDK

一覧と取得

`emails.list`、`emails.listAll`、`emails.iterate`、`emails.get`、`emails.listEvents`。

emails.list

list-emails.ts

const first = await openemail.emails.list({  status: ['queued', 'scheduled'],  from: '[email protected]',  limit: 50,}) const second = first.nextCursor  ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor })  : null

ページは { items, hasMore, nextCursor } です。次のページを取るには、同じフィルターとともに nextCursor を cursor として渡し返してください。

emails.iterate と emails.listAll

iterate-emails.ts

for await (const email of openemail.emails.iterate({ status: 'failed' })) {  console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })

どちらも nextCursor を代わりにたどります。iterate はループがそのページに到達したときだけ取得するので、途中で抜ければリクエストも止まります。listAll はすべてのページを歩いてから 1 つの配列に解決するので、終わりのあるフィルターを与えてください。いずれもキーセットページングなので、オフセットのように、反復中に届いたメッセージのせいで行を飛ばすことはありません。

emails.get と emails.listEvents

get-email.ts

const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)

recipients をアドレスごとに 1 行返すのは get だけです。50 通それぞれが受信者一覧を抱えた一覧は、誰も求めていない分量のレポートです。

パラメーター

statusEmailStatus | EmailStatus[]: 1 つまたは複数のステータス（`queued`、`scheduled`、`sending`、`sent`、`partial`、`cancelled`、`failed`）で、与えたもののいずれかに一致します。サーバーがカンマで分割するため、SDK は配列を 1 つのカンマ区切りの値として送ります。この集合にない値は、未知のものを名指しする 422 になります。
fromstring: 記録されたままの送信アドレスへの完全一致で、それは小文字化された素の `addr@host` です。行は表示名を取り除いて書かれるので、`Acme <[email protected]>` のような山括弧付きアドレスは何にも一致しません。渡した値は比較前に小文字化され、前方一致やドメイン一致ではなく等価比較です。
limitnumber: このページの行数。1 から 100 で既定は 25 です。範囲外の値は丸められずに 422 で拒否されます。
cursorstring: ページングの起点となるメッセージ id（`msg_…`）。オフセットではなくキーセットなので、そのメッセージの `createdAt` より厳密に古い行が返り、ページの途中で届いた送信があなたを追い越して行を押し出すことはありません。このワークスペースのどのメッセージも指さない id は 400 です。

レスポンス: Page<EmailResource>

itemsEmailResource[]: `createdAt` の新しい順に並んだメッセージ 1 ページ分を、API の `data` エンベロープから取り出したものです。一覧の行がアドレスごとの `recipients` の内訳を持つことはありません。それは `get` にあります。
hasMoreboolean: このページより先に、フィルターに一致する行がさらにあるかどうか。2 つ目のカウントクエリではなく、`limit` より 1 行多く取得することで判断します。
nextCursorstring | null: `cursor` として渡し返す id で、最終ページでは null です。`iterate` と `listAll` は、これが null か `hasMore` が false になると止まります。続きがあると言いながらカーソルを示さないページは、永久にループしてしまうからです。
items[].object'email': この一覧の行では常に `'email'` です。
items[].idstring: この API 自身の id、`msg_…` です。他のすべての emails エンドポイントが受け取るのはこれで、カーソルが指すのもこれです。
items[].statusEmailStatus: メッセージが生涯のどこにいるか。`partial` は failed の一種ではなく独立した状態です。一部の受信者にはすでに届いており取り消せないので、再送は誤りです。
items[].modeApiKeyMode: `live` または `test` で、送信したキーから取られます。テスト送信はここに記録され、決して送出されません。
items[].fromstring: 送信が認可されたアドレスで、素のまま小文字で保存されます。そのため `from` に付けた表示名は通信上は出ていきますが、ここには保持されません。これが認可された識別情報であるためオブジェクトではなくプレーンな文字列です。キーの送信スコープ外のアドレス、つまりキーが持つドメイン上にもキーに列挙されてもいないアドレスは 403 で拒否され、使えるアドレスに黙ってすり替えられることは決してありません。
items[].subjectstring | null: 保存されたままの件名。件名なしで記録されたメッセージでは null です。
items[].messageIdstring | null: 当社の id ではなく RFC 5322 の Message-ID です。MIME ができるまでは null で、送出時に送信サービスが書き換えるので、後のバウンスや DSN は別の id を持ち、代わりに `items[].id` で突き合わせます。
items[].threadIdstring | null: このメッセージが属するスレッド。指定または割り当てがあった場合に入り、それ以外は null です。
items[].transportEmailTransport | (string & {}) | null: バイト列がどう出ていったか。送出までは null で、この SDK がまだ名前を持たないトランスポートが破壊的変更にならないよう開いた型になっています。保存済みの記録が、すでに使われていないものを指していることもあります。
items[].attemptsnumber: このメッセージの送出試行回数。初回の前は 0 です。
items[].lastErrorstring | null: 直近の送出エラーを、人向けに書いたもの。何も失敗していない間は null です。
items[].scheduledAtstring | null: メッセージが出る予定の時刻を ISO-8601 で表します。取り消し猶予のない即時送信のときだけ null です。猶予は短い遅延にすぎないので、`cancellableForSeconds` でもここが埋まります。その行の `status` は `scheduled` ではなく `queued` です。
items[].cancellableUntilstring | null: メッセージが出る予定の時刻。遅延されたすべての送信で `scheduledAt` と同じ値を持ち、遅延されなかった送信では null です。これはサーバーが行う判定ではなく表示用のタイムスタンプです。`cancel` は `status` で分岐し、`queued` か `scheduled` の間だけメッセージを止めます。
items[].sentAtstring | null: 実際に出ていった時刻。送出が完了するまで null であり、だからこそ分岐に使うべきはこれではなく `status` です。
items[].tagsRecord<string, string>: 送信時に渡されたラベルを、そのまま返したもので、解釈されることはありません。常にオブジェクトで（何も設定されていなければ null ではなく `{}`）、返されるだけです。このエンドポイントは `status` と `from` で絞り込むので、タグはメッセージを探す手段ではなく、メッセージから読み取るものです。
items[].sourceEmailSource: どの面が送信を要求したか。`composer`、`api`、`mcp`、`ai`、`queue` のいずれかです。このクライアントは `api` です。
items[].createdAtstring: 送信記録が書かれた時刻で、送出より前です。この一覧が並べ替えに使うフィールドであり、カーソルが比較するフィールドでもあります。
items[].trackingEmailTrackingSummary: エンゲージメントの集計。メッセージがトラッキングされた行にのみ存在し、それ以外では存在しません。「これはトラッキングされていたか」への答えは「存在しないこと」であり、`openCount: 0` では「誰も開かなかった」と読まれてしまいます。
items[].tracking.opensboolean: このメッセージがピクセルを付けて出ていったかどうか。今のアカウント設定が何を言っているかではなく、このメッセージに適用されたものです。
items[].tracking.clicksboolean: このメッセージのリンクが書き換えられたかどうか。本文に書き換えるべきリンクがなければ false です。そのときは何も変更されていないからです。
items[].tracking.openedboolean: カウント対象の開封が 1 件でも記録されたかどうか。`openCount > 0` から導出されます。
items[].tracking.clickedboolean: カウント対象のクリックが 1 件でも記録されたかどうか。`clickCount > 0` から導出されます。
items[].tracking.openCountnumber: 人によるものと考えられる開封を、メッセージのすべてのコピーにわたって合計したもの。スキャナーやプライバシープロキシは記録されますが除外され、30 秒以内の再取得は 1 件にまとめられます。
items[].tracking.clickCountnumber: カウント対象のクリックを、コピーにわたって合計したもの。メッセージ単位ではなくリンク単位で重複排除します。数秒差で 2 本のリンクをたどるのは繰り返しではなく 2 つの行為だからです。
items[].tracking.firstOpenAtstring | null: コピーにわたる、カウント対象の最も早い開封。なければ null です。機械的なヒットでこれが動くことはありません。
items[].translationEmailTranslationResource: 一覧の行には決して現れません。翻訳の記録は保存されたリクエストの中にあり、一覧は意図的にそれを取得しないからです。ここに存在しないことは、メッセージが翻訳されたかどうかについて何も語りません。`get` に尋ねてください。