Ruby

一覧と取得

`emails.list`、`emails.list_all`、`emails.iterate`、`emails.get`、`emails.list_events`。

emails.list

list_emails.rb

filters = {status: ["queued", "scheduled"], from: "[email protected]"} first = client.emails.list(**filters, limit: 50)second = client.emails.list(**filters, limit: 50, cursor: first.next_cursor) if first.next_cursor p first.items.size, second&.items&.size

ページは items、has_more?、next_cursor を持つ OpenEmail::Page です。次のページを取得するには、同じフィルターと一緒に next_cursor を cursor: として渡し返してください。

emails.iterate と emails.list_all

iterate_emails.rb

client.emails.iterate(status: "failed") do |email|  warn "#{email[:id]} #{email[:lastError]}"end failures = client.emails.list_all(status: "failed", from: "[email protected]")puts failures.size

どちらも next_cursor を自動的にたどります。iterate は走査がそのページに達したときにだけページを取得するため、ブロック内の break、またはブロックなしで返る Enumerator に対する first や find でリクエストが止まります。一方 list_all はすべてのページをたどってから 1 つの Array を返すため、終わりのあるフィルターを指定してください。どちらもキーセット方式のページ分割なので、走査の途中で届いたメッセージのせいで、オフセット方式のように行が飛ばされることはありません。

emails.get と emails.list_events

get_email.rb

email = client.emails.get("msg_3f9a1c07d2b84e6a9c5b1f20")puts email[:status]p email[:recipients] events = client.emails.list_all_events("msg_3f9a1c07d2b84e6a9c5b1f20")events.each { |event| puts "#{event[:type]} #{event[:createdAt]}" }

recipients を返すのは get だけで、アドレスごとに 1 つの Hash があり、それぞれ独自の status、error、deliveredAt を持ちます。50 件のメッセージがそれぞれ受信者を抱えた一覧は、誰も求めていないレポートのページになってしまいます。

list_events は 1 回の送信のイベント履歴を古い順に読みます：email.accepted、email.queued、email.sent、email.delivered、email.bounced、email.opened などで、それぞれ type によって形が決まる data の Hash を持ちます。list_all_events と iterate_events は履歴全体を自動的にたどります。Webhook は同じイベントの一部を発生時に配信するため、Webhook を受け取り損ねたときはここを確認してください。

パラメーター

statusString or Array<String>: 1 つまたは複数のステータス（`queued`、`scheduled`、`sending`、`sent`、`partial`、`bounced`、`cancelled`、`failed`）で、指定したもののいずれかに一致します。`bounced` はメッセージの送り先のすべての受信者でバウンスしたことを意味し、一部でバウンスして残りに届いたメッセージは `partial` になります。サーバーがカンマで区切るため、gem は Array をカンマ区切りの 1 つの値として送ります。集合にない値は、その未知の値を示す 422 になります。
broadcast_idString: 1 つの一斉配信のコピーだけ。`broadcasts.send` から得た `brd_` の id です。一斉配信が届く一人ひとりに個別のメッセージが送られるため、これは誰に送られ、各コピーがどうなったかを一覧にします。`broadcasts.list_recipients` は同じ人々を、開封、クリック、配信停止とともに一覧にします。
fromString: 記録された送信元アドレスとの完全一致で、記録されるのは小文字にした素の `addr@host` です。行は表示名を取り除いて書き込まれるため、`Acme <[email protected]>` のような山括弧形式のアドレスは何にも一致しません。指定した値は比較の前に小文字に変換され、前方一致やドメインの一致ではなく完全一致で比較されます。
scheduled_fromTime, DateTime or String: この時刻以降にスケジュールされたメッセージだけ。`scheduled_to:` と `status: ["scheduled", "queued"]` と組み合わせると、アプリのカレンダーと同じように、ある期間に送信を待っているものを一覧にします。`scheduledAt` のないメッセージは含まれません。Time、DateTime、またはオフセット付きの ISO 8601 時刻を渡してください。Ruby の Date は日付だけの値として送られ、この 2 つのフィルターはそれを拒否します。
scheduled_toTime, DateTime or String: この時刻以前にスケジュールされたメッセージだけ。`scheduled_from:` が `scheduled_to:` より後だと 422 `invalid_parameter` になります。
limitInteger: このページの行数で、1〜100、既定値は 25。範囲外の値は丸められるのではなく 422 として拒否されます。`list_all` と `iterate` では、取得する各ページのサイズです。
cursorString: ページ分割の起点となるメッセージ id（`msg_…`）。オフセットではなくキーセット方式です：そのメッセージの `createdAt` より厳密に古い行が返るため、ページの途中で届いた送信によって行が押し出され、読み飛ばされることはありません。このワークスペースのどのメッセージも指さない id は 400 `invalid_cursor` になります。
api_keyString: クライアントのキーではなく、このキーで一覧を取得します。

一部のアドレスに絞られたキーは、対象のアドレスから送られたメッセージだけを読みます。ページはその絞り込みの後で区切られるため、最後のページ以外はどれも limit 行を含みます。キーが対象としない from: を指定すると、403 ではなく空の最後のページが返ります。

レスポンス：OpenEmail::Page

itemsArray<Hash>: `createdAt` の新しい順に並んだメッセージ 1 ページ分を、API の `data` エンベロープから取り出したものです。一覧の行がアドレスごとの `recipients` の内訳を持つことはありません。それは `get` にあります。
has_more?Boolean: このページより先に、フィルターに一致する行がさらにあるかどうか。2 つ目のカウントクエリではなく、`limit` より 1 行多く取得することで判断します。
next_cursorString or nil: `cursor:` として渡し返す id で、最後のページでは nil です。`iterate` と `list_all` は、これが nil か `has_more?` が false のときに止まります。続きがあると言いながらカーソルを示さないページは、永遠にループしてしまうからです。

各アイテム

objectString: この一覧の行では常に `email`。
idString: この API 自身の id で、`msg_…` です。emails の他のすべての呼び出しが受け取るもので、カーソルが指すものでもあります。
statusString: メッセージが生涯のどこにいるか。`partial` は failed の一種ではなく独立した状態です。一部の受信者にはすでに届いており取り消せないので、再送は誤りです。`bounced` は送信後にすべての受信者でバウンスしたことを意味し、誰の手元にもありません。理由は `get` の各受信者が示します。
modeString: `live` または `test` で、送信したキーから取られます。テスト送信はここに記録され、決して送出されません。
fromString: 送信が認められたアドレスで、素のアドレスにして小文字で保存されます。そのため `from` で指定した表示名は実際の送信には使われますが、ここには残りません。Hash ではなくただの String なのは、これが認められた送信者そのものだからです：キーの送信スコープ外のアドレス、つまりキーが持つドメインにもなく、キーに名前もないアドレスは 403 で拒否され、黙ってスコープ内のアドレスに置き換えられることはありません。
subjectString or nil: 保存された件名。件名なしで記録されたメッセージでは nil です。
messageIdString or nil: RFC 5322 の Message-ID で、この API の id ではありません。MIME ができるまでは nil で、送り出すときに送信サービスが書き換えるため、後で届くバウンスや DSN は別の id を持ち、代わりに `id` で関連付けられます。
threadIdString or nil: このメッセージが属するスレッドで、指定または割り当てられた場合に存在します。それ以外は nil です。
transportString or nil: バイト列がどの経路で送り出されたか。配送されるまでは nil です。保存済みのレコードには、もう使われていないトランスポートの名前が残っていることがあるため、知らない値はエラーではなく情報として扱ってください。
attemptsInteger: このメッセージの送出試行回数。初回の前は 0 です。
lastErrorString or nil: 最新の配送エラーで、人が読むための文です。何も失敗していない間は nil です。
scheduledAtString or nil: メッセージが送り出される予定の時刻で、ISO 8601 形式です。nil になるのは取り消し猶予のない即時送信だけです：猶予は短い遅延にすぎないため、`cancellableForSeconds` でもこれが設定され、その行の `status` は `scheduled` ではなく `queued` になります。
cancellableUntilString or nil: メッセージが送り出される予定の時刻で、保留された送信では `scheduledAt` と同じ値を持ち、保留されなかった送信では nil です。これは表示するためのタイムスタンプであって、サーバーが行う判定ではありません：`cancel` は `status` で分岐し、メッセージがまだ `queued` か `scheduled` の間だけ止めます。
sentAtString or nil: 送り出された時刻。配送が完了するまでは nil です。分岐にこれではなく `status` を使うべきなのはそのためです。
tagsHash: 送信時に指定したラベルで、そのまま返され、解釈されることはありません。常に Hash で、何も設定されていなければ空になり、nil にはなりません。返されるだけです：この一覧が絞り込みに使うのは `status`、`from`、`broadcast_id` とスケジュールの期間なので、タグはメッセージを探す手段ではなく、メッセージから読み取るものです。
broadcastIdString or nil: このメッセージがコピーの 1 つである `brd_` の一斉配信。単独で送られたメッセージでは nil です。
sourceString: どの面が送信を要求したか。`composer`、`api`、`mcp`、`ai`、`queue` のいずれかです。このクライアントは `api` です。
createdAtString: 送信記録が書かれた時刻で、送出より前です。この一覧が並べ替えに使うフィールドであり、カーソルが比較するフィールドでもあります。
trackingHash: エンゲージメントの概要で、メッセージがトラッキングされた行にだけ存在し、それ以外にはありません。キーがないことが「トラッキングされたか」への答えです。`openCount` が 0 では「誰も開封しなかった」と読めてしまうからです。
translationHash: 一覧の行には決して現れません。翻訳の記録は保存されたリクエストの中にあり、一覧は意図的にそれを取得しないからです。ここに存在しないことは、メッセージが翻訳されたかどうかについて何も語りません。`get` に尋ねてください。

アイテムのトラッキング

opensBoolean: このメッセージがピクセルを付けて出ていったかどうか。今のアカウント設定が何を言っているかではなく、このメッセージに適用されたものです。
clicksBoolean: このメッセージのリンクが書き換えられたかどうか。ボディに書き換えるリンクがなかった場合は、何も変更されていないため false です。
openedBoolean: カウントされた開封が記録されたかどうかで、`openCount` が 0 より大きいかから導かれます。
clickedBoolean: カウントされたクリックが記録されたかどうかで、`clickCount` が 0 より大きいかから導かれます。
openCountInteger: 人によるものと考えられる開封を、メッセージのすべてのコピーにわたって合計したもの。スキャナーやプライバシープロキシは記録されますが除外され、30 秒以内の再取得は 1 件にまとめられます。
clickCountInteger: カウント対象のクリックを、コピーにわたって合計したもの。メッセージ単位ではなくリンク単位で重複排除します。数秒差で 2 本のリンクをたどるのは繰り返しではなく 2 つの行為だからです。
firstOpenAtString or nil: すべてのコピーを通じて最も早い、カウントされた開封。まだない間は nil です。機械によるアクセスでこれが動くことはありません。