Ruby

開封とクリックのトラッキング

`emails.get_tracking` と `tracking` 名前空間全体。

1 通のメッセージ

tracking.rb

report = client.emails.get_tracking("msg_3f9a1c07d2b84e6a9c5b1f20") puts "#{report[:openCount]} opens from #{report[:recipients].size} recipients"report[:links].each { |link| puts "#{link[:url]} #{link[:clickCount]}" }

トラッキングされなかったメッセージは、空のレポートではなく OpenEmail::NotFoundError を送出し、その not_found? は true です。「何も記録していない」と「誰も開封しなかった」は別の答えであり、同じレスポンスを共有してはいけません。テストキーで送られたメッセージは決してトラッキングされないため、常にこれを送出します。

メールボックス全体

tracking_report.rb

client.tracking.list(opened: false, days: 7, limit: 100)client.tracking.get_stats(days: 30, offset_minutes: Time.now.utc_offset / 60)client.tracking.get("msg_3f9a1c07d2b84e6a9c5b1f20")client.tracking.list_opens("msg_3f9a1c07d2b84e6a9c5b1f20", include_machine: true)client.tracking.list_clicks("msg_3f9a1c07d2b84e6a9c5b1f20")

list、list_opens、list_clicks は 1 つの OpenEmail::Page を返し、list_all、iterate、list_all_opens、iterate_opens、list_all_clicks、iterate_clicks はすべてのページを自動的にたどります。get、list_opens、list_clicks は、msg_… の送信 id とトラッキングレコード自身の tmsg_… のどちらも受け取ります。

emails のメソッドではなく独立した名前空間になっているのは、網羅性のためです：emails が一覧にする送信レコードは、この API が扱ったメールにしか存在しません。コンポーザー、MCP ツール、アシスタントはどれも送信レコードなしで送信するため、emails に基づくレポートはメールボックスではなく API のトラフィックについてのレポートになってしまいます。

数字を正直に読む

組	意味
opens と clicks	適用されたもの。メッセージがピクセル付きで、あるいは書き換えられたリンク付きで出ていったかどうかです。
opened と clicked	実際に起きたこと。
openCount	カウント対象のヒット。スキャナーとプライバシープロキシは除外されます。
openCountRaw	すべてのヒット。これをエンゲージメントとして引用すると、開封率が 100% を超えます。
attributable	読まれたことを、そもそも特定の受信者に結び付けられるかどうか。

tracking.get_stats の率は「トラッキングされた」メッセージに対するもので、送信したすべてに対するものではありません。そうでなければ、10 通に 1 通をトラッキングするメールボックスは、率が急落したように見えてしまいます。openRate と clickRate は 42.5 のように小数点以下 1 桁に丸めたパーセンテージで、0 から 1 の間の割合ではありません。

パラメーター: tracking.list

openedBoolean: `true` はカウント対象の開封が 1 件以上あるメッセージを、`false` は開封のないトラッキング済みメッセージを選びます。どちらも既定ではなく、`false` が未トラッキングのメールを意味することはありません。それらはこの一覧にまったく現れません。
clickedBoolean: カウント対象のクリックについての同じフィルターで、`opened` とは独立に適用されます。両方を指定することもでき、その場合メッセージは両方を満たす必要があります。
daysInteger: 現在から何日さかのぼるかで、1〜365、既定値は 30。範囲外は 422 になります。期間はトラッキングレコードが作られた時刻で測られ、送信が実際に送り出されたレコードだけが一覧に含まれます。
minutesInteger: 代わりに分単位で指定する期間で、1〜527040。両方を指定すると `days` より優先されます。1 日より短い期間には、より細かい `grain` が必要です。
grainString: `minute`、`hour`、`day` のいずれかで、既定値は `day`。期間の始まりを切り捨てるだけなので、この一覧は同じ粒度で読んだ `get_stats` と一致し、レスポンスの形には何も影響しません。
limitInteger: 1 ページあたりのレポート数で、1〜200、既定値は 50、新しい順です。次のページを取得するには、同じフィルターと一緒にページの `next_cursor` を `cursor:` として渡し返すか、`list_all` と `iterate` に期間全体をたどらせてください。
cursorString: 前のページの `next_cursor` で、`tmsg_` の id です。
api_keyString: クライアントのキーではなく、このキーで一覧を取得します。

レスポンス：トラッキングレポート

emails.get_tracking と tracking.get は 1 つのレポートを Symbol キーの Hash として返し、tracking.list はそれらのページを返します。

objectString: `tracking.get`、`tracking.list`、`emails.get_tracking` を通じて単独で取得したレポートでは常に `tracking`。`emails.get` から得たメッセージに `tracking` として入れ子になった同じレポートには、このキーがありません。そこではレポートは取得されたものではなく、そのメッセージの一部だからです。
idString: トラッキングレコード自身の id で、`tmsg_…` です。`list_opens` と `list_clicks` はこれをキーとし、これらに `msg_…` を渡すと、まずそれに対応するこの id が検索されます。
sendIdString or nil: これに対応する `msg_…` の送信で、送信レコードが書き込まれなかった場合は nil です。コンポーザー、MCP の `sendEmail`、アシスタントはどれも送信レコードなしで送信します。トラッキングは API のトラフィックだけでなく、メールボックス全体を対象とします。
threadIdString or nil: 送信後に設定され、閲覧用の UI がメッセージを再び見つけられるようにします。ドライバーが何も報告しなかった場合は nil です。これに依存する処理はありません：これが nil のレコードも集計に含まれます。
messageIdString or nil: RFC 5322 の Message-ID で、この API の id ではありません。これも送信後に設定され、トランスポートが値を返さなかった場合は nil です。
subjectString or nil: 送信時点の件名。件名なしで記録されたメッセージでは nil です。
fromString: 送信元アドレス。送信レコードから結合するのではなく、このレコードにコピーして保持する。レポートは事後かなり経ってから読まれるものであり、そうしなければ、その後に修正または削除されたアドレスが過去の記録を書き換えてしまう。
sourceString: どの経路から送信されたか：`composer`、`api`、`mcp`、`ai`、`queue` のいずれか。この gem がまだ名前を知らない経路が現れることもあるため、未知の値はエラーではなく情報として扱ってください。
sentAtString or nil: メッセージが送り出された時刻で、ISO 8601 形式です。送信が完了しなかったレコードでは nil です。`tracking.list` はそれらを除外しますが、`get` は除外しません。
opensBoolean: このメッセージにピクセルが実際に適用されたかどうか。現在のアカウント設定ではなく、実行時に何が行われたかを表す。
clicksBoolean: このメッセージのリンクが書き換えられたかどうか。ボディにリンクがなかった場合は false です。そのときは何も変更されておらず、そうでないと主張するレコードは実際のバイト列と整合しないからです。
openedBoolean: コピーにわたってカウント対象の開封が 1 件でも記録されたかどうか。`opens` と併せて読んでください。収集していないからデータがないことと、誰もメッセージを読まなかったことは別の事実です。
clickedBoolean: カウント対象のクリックが 1 件でも記録されたかどうか。開封より強い証拠です。画像がブロックされる頻度は、リンクがたどられない頻度よりはるかに高いからです。
attributableBoolean: ここでのすべての閲覧を、特定の受信者に結び付けられるかどうか。帰属できないコピーにカウント対象の活動が現れた瞬間に false になります。これは複数宛先の場合で、1 つの本文が 1 つのトークンでリスト全体に届くケースです。「Bob はこれを開いていない」と書く前に確認してください。
openCountInteger: 人によるものと考えられる開封を、コピーにわたって合計したもの。機械的なヒットは除外され、30 秒以内の繰り返しは 1 件にまとめられるので、読み手の前に出すべき数字はこれです。
clickCountInteger: カウント対象のクリックを、コピーにわたって合計したもの。メッセージ単位ではなくリンク単位で重複排除するので、数秒差でたどられた異なる 2 本のリンクは 2 クリックです。
openCountRawInteger: スキャナーやプライバシープロキシを含む、すべてのピクセル取得。`openCountRaw` から `openCount` を引いた数が除外された件数で、機械による取得と 30 秒以内の繰り返しを合わせたものです。フィルタリングが行われたことを示す唯一の証拠でもあります。
clickCountRawInteger: 書き換えられたリンクへのすべての訪問。機械的なヒットと繰り返しを含みます。
firstOpenAtString or nil: すべてのコピーを通じて最も早い、カウントされた開封。まだない間は nil です。機械によるアクセスでこれが動くことはありません。
lastOpenAtString or nil: すべてのコピーを通じて最も新しい、カウントされた開封。まだない間は nil です。
firstClickAtString or nil: すべてのコピーを通じて最も早い、カウントされたクリック。まだない間は nil です。
lastClickAtString or nil: すべてのコピーを通じて最も新しい、カウントされたクリック。まだない間は nil です。
recipientsArray<Hash>: トラッキング対象のコピーごとに 1 エントリ。トランスポートが人ごとにバイト列を変えられる場合は受信者ごとに、そうでない場合は共有エントリが 1 つだけ入る。共有エントリは実際に何らかのヒットが記録された場合にのみ残るため、何も起きていない「誰か」の行が実名の隣に並ぶことはない。
linksArray<Hash>: このメッセージ内で書き換えられたすべてのリンク。本文中の位置順に並ぶ。書き換えが行われなかった場合は空になる。`clicks` を無効にして送信したメッセージや、本文にリンクが 1 つもなかったメッセージがこれにあたる。

recipients の各エントリ

emailString or nil: このコピーの送り先で、送信時点のアドレスを小文字にしたものです。`attributed` が false のときに限って nil です。
kindString or nil: `to`、`cc`、`bcc` のいずれか：アドレスがどのヘッダーに現れたかを示すため、レポートはメッセージと同じように読めます。どの 1 つのアドレスにも属さない共有コピーでは nil です。
attributedBoolean: この行が個人を特定しているかどうか。`email` より先にこの値を読むこと。false は共有コピーであり、ヒットが 1 件でも記録された時点で一覧に現れる。受信者が 1 人だけのメッセージであっても、そのヒットに名前を付けることは、この仕組みが提供できない唯一の事実を捏造することになる。
openCountInteger: このコピー単独でのカウント対象の開封数。除外条件はメッセージ全体の合計と同じで、マシンによるヒットは除外され、30 秒以内の繰り返しは 1 件にまとめられる。
clickCountInteger: このコピー単独でのカウント対象のクリック数。重複排除はコピー単位ではなくリンク単位で行われる。
firstOpenAtString or nil: このコピーで最も早い、カウントされた開封。まだない間は nil です。
lastOpenAtString or nil: このコピーで最も新しい、カウントされた開封。まだない間は nil です。
firstClickAtString or nil: このコピーで最も早い、カウントされたクリック。まだない間は nil です。
lastClickAtString or nil: このコピーで最も新しい、カウントされたクリック。まだない間は nil です。

links の各エントリ

idString: リンク自身の id で、`lnk_…` です。クリックの行の `linkId` が示す値なので、`list_clicks` から得たアクセスをここのエントリと照合できます。
urlString: リンクの実際の行き先で、書き換え前のメッセージにあったとおりのものです。リダイレクターは id からこれを引き当て、訪問者をそこへ送ります。
labelString or nil: メッセージに現れたとおりのアンカーテキスト。画像や URL だけのリンクのようにテキストがない場合は nil です。レポートが、トラッキング用のパラメーターが 3 つ付いた URL を引用する代わりに「料金のリンク」と言えるようにするためのもので、`url` の代わりになることはありません。
clickCountInteger: このリンクへのカウント対象の訪問数を、全コピーで合計したもの。メッセージの `clickCount` と同じ、リンク単位の 30 秒ウィンドウが適用される。
clickCountRawInteger: このリンクへのすべての訪問。マシンによるヒットと繰り返しも含む。