Python
一覧と取得
`emails.list`、`emails.list_all`、`emails.iterate`、`emails.get`、`emails.list_events`。
emails.list
from openemail import openemail first = openemail.emails.list(status=['queued', 'scheduled'], from_='[email protected]', limit=50) if first['nextCursor']: second = openemail.emails.list( status=['queued', 'scheduled'], from_='[email protected]', limit=50, cursor=first['nextCursor'], )ページは {'items': [...], 'hasMore': ..., 'nextCursor': ...} です。次のページを取るには、同じフィルターとともに nextCursor を cursor として渡し返してください。
emails.iterate と emails.list_all
import sys from openemail import openemail for email in openemail.emails.iterate(status='failed'): print(email['id'], email['lastError'], file=sys.stderr) failures = openemail.emails.list_all(status='failed', from_='[email protected]')どちらも nextCursor を代わりにたどります。iterate はループがそのページに到達したときだけ取得するジェネレーターなので、途中で抜ければリクエストも止まります。list_all はすべてのページを歩いてから 1 つのリストを返すので、終わりのあるフィルターを与えてください。いずれもキーセットページングなので、オフセットのように、反復中に届いたメッセージのせいで行を飛ばすことはありません。
emails.get と emails.list_events
from openemail import openemail email = openemail.emails.get('msg_…')print(email['status'], email['recipients']) events = openemail.emails.list_all_events('msg_…')for event in events: print(event['type'], event['createdAt'])recipients をアドレスごとに 1 行返すのは get だけです。50 通それぞれが受信者一覧を抱えた一覧は、誰も求めていない分量のレポートです。
パラメーター
statusEmailStatus | Sequence[EmailStatus]- 1 つまたは複数のステータス（`queued`、`scheduled`、`sending`、`sent`、`partial`、`bounced`、`cancelled`、`failed`）で、与えたもののいずれかに一致します。サーバーがカンマで分割するため、SDK はリストを 1 つのカンマ区切りの値として送ります。この集合にない値は、未知のものを名指しする 422 になります。
broadcast_idstr- 1 つの一斉配信のコピーだけで、`broadcasts.send` から得た `brd_` ID を指定します。一斉配信が届いた一人ひとりに独自のメッセージが届くので、これで誰に送られ、各コピーがどうなったかが一覧できます。`broadcasts.list_recipients` は同じ人たちを、開封、クリック、登録解除とあわせて一覧します。
from_str- 記録されたままの送信アドレスへの完全一致で、それは小文字化された素の `addr@host` です。行は表示名を取り除いて書かれるので、`Acme <[email protected]>` のような山括弧付きアドレスは何にも一致しません。渡した値は比較前に小文字化され、前方一致やドメイン一致ではなく等価比較です。末尾のアンダースコアは、`from` が Python の予約語であるために付いています。
limitint- このページの行数。1 から 100 で既定は 25 です。範囲外の値は丸められずに 422 で拒否されます。
cursorstr- ページングの起点となるメッセージ id（`msg_…`）。オフセットではなくキーセットなので、そのメッセージの `createdAt` より厳密に古い行が返り、ページの途中で届いた送信があなたを追い越して行を押し出すことはありません。このワークスペースのどのメッセージも指さない id は 400 です。
scheduled_fromdatetime | str- この時刻以降に予約されたメッセージだけ。`datetime`、またはタイムゾーン付きの ISO-8601 の時刻で指定します。`scheduledAt` のないメッセージは除外されるので、`scheduled_to` と `status=['queued', 'scheduled']` と組み合わせれば、ある期間内に送信を待っているものを一覧できます。
scheduled_todatetime | str- この時刻以前に予約されたメッセージだけ。これより後の `scheduled_from` を指定すると、`scheduledTo` に対する 422 `invalid_parameter` になります。
レスポンス: Page[EmailResource]
itemslist[EmailResource]- `createdAt` の新しい順に並んだメッセージ 1 ページ分を、API の `data` エンベロープから取り出したものです。一覧の行がアドレスごとの `recipients` の内訳を持つことはありません。それは `get` にあります。
hasMorebool- このページより先に、フィルターに一致する行がさらにあるかどうか。2 つ目のカウントクエリではなく、`limit` より 1 行多く取得することで判断します。
nextCursorstr | None- `cursor` として渡し返す id で、最終ページでは null です。`iterate` と `list_all` は、これが null か `hasMore` が false になると止まります。続きがあると言いながらカーソルを示さないページは、永久にループしてしまうからです。
items[].objectLiteral['email']- この一覧の行では常に `'email'` です。
items[].idstr- この API 自身の id、`msg_…` です。他のすべての emails エンドポイントが受け取るのはこれで、カーソルが指すのもこれです。
items[].statusEmailStatus- メッセージが生涯のどこにいるか。`partial` は failed の一種ではなく独立した状態です。一部の受信者にはすでに届いており取り消せないので、再送は誤りです。`bounced` は送信後にすべての受信者でバウンスしたことを意味し、誰の手元にもありません。理由は `get` の各受信者が示します。
items[].modeApiKeyMode- `live` または `test` で、送信したキーから取られます。テスト送信はここに記録され、決して送出されません。
items[].fromstr- 送信が認可されたアドレスで、素のまま小文字で保存されます。そのため `from` に付けた表示名は通信上は出ていきますが、ここには保持されません。これが認可された識別情報であるため、dict ではなくプレーンな文字列です。キーの送信スコープ外のアドレス、つまりキーが持つドメイン上にもキーに列挙されてもいないアドレスは 403 で拒否され、使えるアドレスに黙ってすり替えられることは決してありません。
items[].subjectstr | None- 保存されたままの件名。件名なしで記録されたメッセージでは null です。
items[].messageIdstr | None- 当社の id ではなく RFC 5322 の Message-ID です。MIME ができるまでは null で、送出時に送信サービスが書き換えるので、後のバウンスや DSN は別の id を持ち、代わりに `items[].id` で突き合わせます。
items[].threadIdstr | None- このメッセージが属するスレッド。指定または割り当てがあった場合に入り、それ以外は null です。
items[].transportEmailTransport | str | None- バイト列がどう出ていったか。送出までは null で、この SDK がまだ名前を持たないトランスポートが破壊的変更にならないよう開いた型になっています。保存済みの記録が、すでに使われていないものを指していることもあります。
items[].attemptsint- このメッセージの送出試行回数。初回の前は 0 です。
items[].lastErrorstr | None- 直近の送出エラーを、人向けに書いたもの。何も失敗していない間は null です。
items[].scheduledAtstr | None- メッセージが出る予定の時刻を ISO-8601 で表します。取り消し猶予のない即時送信のときだけ null です。猶予は短い遅延にすぎないので、`cancellableForSeconds` でもここが埋まります。その行の `status` は `scheduled` ではなく `queued` です。
items[].cancellableUntilstr | None- メッセージが出る予定の時刻。遅延されたすべての送信で `scheduledAt` と同じ値を持ち、遅延されなかった送信では null です。これはサーバーが行う判定ではなく表示用のタイムスタンプです。`cancel` は `status` で分岐し、`queued` か `scheduled` の間だけメッセージを止めます。
items[].sentAtstr | None- 実際に出ていった時刻。送出が完了するまで null であり、だからこそ分岐に使うべきはこれではなく `status` です。
items[].tagsdict[str, str]- 送信時に指定したラベルで、そのまま返され、解釈されることはありません。常に dict で（何も設定しなければ `{}`、null にはなりません）、返されるだけです。この呼び出しが絞り込みに使うのは `status`、`from_`、`broadcast_id`、`scheduled_from`、`scheduled_to` なので、タグはメッセージから読むものであり、メッセージを探す手段ではありません。
items[].broadcastIdstr | None- このメッセージがコピーである `brd_` 一斉配信。単独で送ったメッセージでは null です。
items[].sourceEmailSource | str- どの面が送信を要求したか。`composer`、`api`、`mcp`、`ai`、`oauth`、`form` のいずれかです。API キーを使うこのクライアントは `api`、アクセストークンを使うこのクライアントは `oauth` です。
items[].createdAtstr- 送信記録が書かれた時刻で、送出より前です。この一覧が並べ替えに使うフィールドであり、カーソルが比較するフィールドでもあります。
items[].trackingNotRequired[EmailTrackingSummary]- エンゲージメントの集計。メッセージがトラッキングされた行にのみ存在し、それ以外では存在しません。「これはトラッキングされていたか」への答えは「存在しないこと」であり、`openCount: 0` では「誰も開かなかった」と読まれてしまいます。
items[].tracking.opensbool- このメッセージがピクセルを付けて出ていったかどうか。今のアカウント設定が何を言っているかではなく、このメッセージに適用されたものです。
items[].tracking.clicksbool- このメッセージのリンクが書き換えられたかどうか。本文に書き換えるべきリンクがなければ false です。そのときは何も変更されていないからです。
items[].tracking.openedbool- カウント対象の開封が 1 件でも記録されたかどうか。`openCount > 0` から導出されます。
items[].tracking.clickedbool- カウント対象のクリックが 1 件でも記録されたかどうか。`clickCount > 0` から導出されます。
items[].tracking.openCountint- 人によるものと考えられる開封を、メッセージのすべてのコピーにわたって合計したもの。スキャナーやプライバシープロキシは記録されますが除外され、30 秒以内の再取得は 1 件にまとめられます。
items[].tracking.clickCountint- カウント対象のクリックを、コピーにわたって合計したもの。メッセージ単位ではなくリンク単位で重複排除します。数秒差で 2 本のリンクをたどるのは繰り返しではなく 2 つの行為だからです。
items[].tracking.firstOpenAtstr | None- コピーにわたる、カウント対象の最も早い開封。なければ null です。機械的なヒットでこれが動くことはありません。
items[].translationNotRequired[EmailTranslationResource]- 一覧の行には決して現れません。翻訳の記録は保存されたリクエストの中にあり、一覧は意図的にそれを取得しないからです。ここに存在しないことは、メッセージが翻訳されたかどうかについて何も語りません。`get` に尋ねてください。