PHP
一覧と取得
`emails->list`、`emails->listAll`、`emails->iterate`、`emails->get`、`emails->listEvents`。
emails->list
$filters = ['status' => ['queued', 'scheduled'], 'from' => '[email protected]']; $first = $client->emails->list(...$filters, limit: 50);$second = $first->hasMore ? $client->emails->list(...$filters, limit: 50, cursor: $first->nextCursor) : null; echo count($first), ' ', $second === null ? 0 : count($second), PHP_EOL;ページは items、hasMore、nextCursor を持つ OpenEmail\Result\Page です。次のページを取得するには、同じフィルターと一緒に nextCursor を cursor: として渡し返してください。...$filters のように 1 つのフィルターの配列を各呼び出しに展開すれば、フィルターを同じに保てます。
emails->iterate と emails->listAll
foreach ($client->emails->iterate(status: 'failed') as $email) { error_log($email['id'] . ' ' . ($email['lastError'] ?? ''));} $failures = $client->emails->listAll(status: 'failed', from: '[email protected]');echo count($failures), PHP_EOL;どちらも nextCursor を自動的にたどります。iterate は走査がそのページに達したときにだけページを取得する Generator を返すため、foreach から break で抜ければリクエストも止まります。一方 listAll はすべてのページをたどってから 1 つの配列を返すため、終わりのあるフィルターを指定してください。どちらもキーセット方式のページ分割なので、走査の途中で届いたメッセージのせいで、オフセット方式のように行が飛ばされることはありません。
emails->get と emails->listEvents
$email = $client->emails->get('msg_3f9a1c07d2b84e6a9c5b1f20');echo $email['status'], PHP_EOL;print_r($email['recipients']); $events = $client->emails->listAllEvents('msg_3f9a1c07d2b84e6a9c5b1f20'); foreach ($events as $event) { echo $event['type'], ' ', $event['createdAt'], PHP_EOL;}recipients を返すのは get だけで、アドレスごとに 1 つの配列があり、それぞれ独自の status、error、deliveredAt を持ちます。50 件のメッセージがそれぞれ受信者を抱えた一覧は、誰も求めていないレポートのページになってしまいます。
listEvents は 1 回の送信のイベント履歴を古い順に読みます。email.accepted、email.queued、email.sent、email.delivered、email.bounced、email.opened などで、それぞれ type によって形が決まる data 配列を持ちます。listAllEvents と iterateEvents は履歴全体を自動的にたどります。Webhook は同じイベントの一部を発生時に配信するため、Webhook を受け取り損ねたときはここを確認してください。
パラメーター
statusstring or array- 1 つまたは複数のステータス（`queued`、`scheduled`、`sending`、`sent`、`partial`、`bounced`、`cancelled`、`failed`）で、指定したもののいずれかに一致します。`bounced` はメッセージの送り先のすべての受信者でバウンスしたことを意味し、一部でバウンスして残りに届いたメッセージは `partial` になります。サーバーがカンマで区切るため、クライアントは配列をカンマ区切りの 1 つの値として送ります。集合にない値は、その未知の値を示す 422 になります。
broadcastIdstring- 1 つの一斉配信のコピーだけ。`broadcasts->send` から得た `brd_` の id です。一斉配信が届く一人ひとりに個別のメッセージが送られるため、これは誰に送られ、各コピーがどうなったかを一覧にします。`broadcasts->listRecipients` は同じ人々を、開封、クリック、配信停止とともに一覧にします。
fromstring- 記録された送信元アドレスとの完全一致で、記録されるのは小文字にした素の `addr@host` です。行は表示名を取り除いて書き込まれるため、`Acme <[email protected]>` のような山括弧形式のアドレスは何にも一致しません。指定した値は比較の前に小文字に変換され、前方一致やドメインの一致ではなく完全一致で比較されます。
scheduledFromDateTimeInterface or string- この時刻以降にスケジュールされたメッセージだけ。`scheduledTo:` と `status: ['scheduled', 'queued']` と組み合わせると、アプリのカレンダーと同じように、ある期間に送信を待っているものを一覧にします。`scheduledAt` のないメッセージは含まれません。UTC の時刻として送られる `DateTimeInterface`、またはオフセット付きの ISO 8601 時刻を渡してください。時刻のない日付文字列は、この 2 つのフィルターでは拒否されます。
scheduledToDateTimeInterface or string- この時刻以前にスケジュールされたメッセージだけ。`scheduledFrom:` が `scheduledTo:` より後だと 422 `invalid_parameter` になります。
limitint- このページの行数で、1〜100、既定値は 25。範囲外の値は丸められるのではなく 422 として拒否されます。`listAll` と `iterate` では、取得する各ページのサイズです。
cursorstring- ページ分割の起点となるメッセージ id（`msg_…`）。オフセットではなくキーセット方式です：そのメッセージの `createdAt` より厳密に古い行が返るため、ページの途中で届いた送信によって行が押し出され、読み飛ばされることはありません。このワークスペースのどのメッセージも指さない id は 400 `invalid_cursor` になります。
apiKeystring- クライアントのキーではなく、このキーで一覧を取得します。
一部のアドレスに絞られたキーは、対象のアドレスから送られたメッセージだけを読みます。ページはその絞り込みの後で区切られるため、最後のページ以外はどれも limit 行を含みます。キーが対象としない from: を指定すると、403 ではなく空の最後のページが返ります。
レスポンス：OpenEmail\Result\Page
itemsarray- `createdAt` の新しい順に並んだメッセージ 1 ページ分を、API の `data` エンベロープから取り出したものです。一覧の行がアドレスごとの `recipients` の内訳を持つことはありません。それは `get` にあります。
hasMorebool- このページより先に、フィルターに一致する行がさらにあるかどうか。2 つ目のカウントクエリではなく、`limit` より 1 行多く取得することで判断します。
nextCursorstring or null- `cursor:` として渡し返す id で、最後のページでは null です。`iterate` と `listAll` は、これが null か `hasMore` が false のときに止まります。続きがあると言いながらカーソルを示さないページは、永遠にループしてしまうからです。
各アイテム
objectstring- この一覧の行では常に `email`。
idstring- この API 自身の id で、`msg_…` です。emails の他のすべての呼び出しが受け取るもので、カーソルが指すものでもあります。
statusstring- メッセージが生涯のどこにいるか。`partial` は failed の一種ではなく独立した状態です。一部の受信者にはすでに届いており取り消せないので、再送は誤りです。`bounced` は送信後にすべての受信者でバウンスしたことを意味し、誰の手元にもありません。理由は `get` の各受信者が示します。
modestring- `live` または `test` で、送信したキーから取られます。テスト送信はここに記録され、決して送出されません。
fromstring- 送信が認められたアドレスで、素のアドレスにして小文字で保存されます。そのため `from` で指定した表示名は実際の送信には使われますが、ここには残りません。配列ではなくただの文字列なのは、これが認められた送信者そのものだからです。キーの送信スコープ外のアドレス、つまりキーが持つドメインにもなく、キーに名前もないアドレスは 403 で拒否され、黙ってスコープ内のアドレスに置き換えられることはありません。
subjectstring or null- 保存された件名。件名なしで記録されたメッセージでは null です。
messageIdstring or null- RFC 5322 の Message-ID で、この API の id ではありません。MIME ができるまでは null で、送り出すときに送信サービスが書き換えるため、後で届くバウンスや DSN は別の id を持ち、代わりに `id` で関連付けられます。
threadIdstring or null- このメッセージが属するスレッドで、指定または割り当てられた場合に存在します。それ以外は null です。
transportstring or null- バイト列がどの経路で送り出されたか。配送されるまでは null です。保存済みのレコードには、もう使われていないトランスポートの名前が残っていることがあるため、知らない値はエラーではなく情報として扱ってください。
attemptsint- このメッセージの送出試行回数。初回の前は 0 です。
lastErrorstring or null- 最新の配送エラーで、人が読むための文です。何も失敗していない間は null です。
scheduledAtstring or null- メッセージが送り出される予定の時刻で、ISO 8601 形式です。null になるのは取り消し猶予のない即時送信だけです。猶予は短い遅延にすぎないため、`cancellableForSeconds` でもこれが設定され、その行の `status` は `scheduled` ではなく `queued` になります。
cancellableUntilstring or null- メッセージが出る予定の時刻。遅延されたすべての送信で `scheduledAt` と同じ値を持ち、遅延されなかった送信では null です。これはサーバーが行う判定ではなく表示用のタイムスタンプです。`cancel` は `status` で分岐し、`queued` か `scheduled` の間だけメッセージを止めます。
sentAtstring or null- 送り出された時刻。配送が完了するまでは null です。分岐にこれではなく `status` を使うべきなのはそのためです。
tagsarray- 送信時に指定したラベルで、そのまま返され、解釈されることはありません。常に配列で、何も設定されていなければ空になり、null にはなりません。返されるだけです。この一覧が絞り込みに使うのは `status`、`from`、`broadcastId` とスケジュールの期間なので、タグはメッセージを探す手段ではなく、メッセージから読み取るものです。
broadcastIdstring or null- このメッセージがコピーである `brd_` 一斉配信。単独で送ったメッセージでは null です。
sourcestring- どの面が送信を要求したか。`composer`、`api`、`mcp`、`ai`、`queue` のいずれかです。このクライアントは `api` です。
createdAtstring- 送信記録が書かれた時刻で、送出より前です。この一覧が並べ替えに使うフィールドであり、カーソルが比較するフィールドでもあります。
trackingarray- エンゲージメントの概要で、メッセージがトラッキングされた行にだけ存在し、それ以外にはありません。キーがないことが「トラッキングされたか」への答えです。`openCount` が 0 では「誰も開封しなかった」と読めてしまうからです。そのため、キーがあると決めつけず `?? null` で読んでください。
translationarray- 一覧の行には決して現れません。翻訳の記録は保存されたリクエストの中にあり、一覧は意図的にそれを取得しないからです。ここに存在しないことは、メッセージが翻訳されたかどうかについて何も語りません。`get` に尋ねてください。
アイテムのトラッキング
opensbool- このメッセージがピクセルを付けて出ていったかどうか。今のアカウント設定が何を言っているかではなく、このメッセージに適用されたものです。
clicksbool- このメッセージのリンクが書き換えられたかどうか。ボディに書き換えるリンクがなかった場合は、何も変更されていないため false です。
openedbool- カウントされた開封が記録されたかどうかで、`openCount` が 0 より大きいかから導かれます。
clickedbool- カウントされたクリックが記録されたかどうかで、`clickCount` が 0 より大きいかから導かれます。
openCountint- 人によるものと考えられる開封を、メッセージのすべてのコピーにわたって合計したもの。スキャナーやプライバシープロキシは記録されますが除外され、30 秒以内の再取得は 1 件にまとめられます。
clickCountint- カウント対象のクリックを、コピーにわたって合計したもの。メッセージ単位ではなくリンク単位で重複排除します。数秒差で 2 本のリンクをたどるのは繰り返しではなく 2 つの行為だからです。
firstOpenAtstring or null- コピーにわたる、カウント対象の最も早い開封。なければ null です。機械的なヒットでこれが動くことはありません。