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

独立した 2 つのスイッチがあり、送信元アドレスまたは「すべてのアドレス」でオフにされていない限り、どちらもオンです。opens は 1×1 の画像を付け、clicks は本文の新しい部分のリンクを書き換えます。返信の下に引用された履歴は他人のメッセージなので、そのまま残されます。送信時に tracking: { opens, clicks } を指定すると 1 通について決められ（どちらの方向にも指定できるので、false はプログラムがそのアドレスの設定を断る方法です）、省略したフィールドは送信元アドレスの設定、次いで「すべてのアドレス」の設定にフォールバックします。この API がワークスペースに代わって選んだ既定値にフォールバックすることはありません。

{    "from": "Acme Billing <[email protected]>",    "to": ["[email protected]"],    "subject": "Your September invoice",    "html": "<p>Invoice attached.</p>",    "tracking": { "opens": true, "clicks": true }  }

1 通あたり最大 100 か所のリンク先が、それぞれ 1 度だけ書き換えられます。ヘッダー画像、ボタン、フッターからリンクされた同じ URL は 1 行にまとまります。同じ問いを 3 回しているだけだからです。上限を超えた残りのリンクは、書かれたとおりに残されます。トラッキングされないリンクでも動作しますし、メッセージが最後の 200 本のリンクを黙って失うことは、不完全なレポートよりはるかに悪い失敗です。

書き換えられたリンクとピクセルは、既定では OpenEmail の API ホストを指します。送信ドメインが tracking.status が active のカスタムトラッキングドメインを持つ場合、そのドメインからの新しいメールは代わりに https://<tracking host>/t/... を使います。設定は PATCH /domains/{id} で行います。

これが /emails 上の数フィールドではなく独立したリソースになっているのは、カバー範囲のためです。あの一覧が持つのは送信レコードであり、コンポーザー、MCP ツール、アシスタントはいずれも送信レコードを書かずに送信します。それを土台にしたレポートは、メールボックスについてのレポートではなく、あなたの API トラフィックについてのレポートになってしまいます。

{    "object": "tracking",    "id": "tmsg_9c1f7b2e4a5d40b8a3e61d2f",    "sendId": "msg_c5f21cc6bfec4e848caf905b",    "threadId": "thread_2f9b…",    "messageId": "<2598…@acme.com>",    "subject": "Your September invoice",    "from": "[email protected]",    "source": "api",    "sentAt": "2026-08-29T08:19:08.000Z",    "opens": true,    "clicks": true,    "opened": true,    "clicked": true,    "attributable": true,    "openCount": 3,    "openCountRaw": 7,    "clickCount": 1,    "clickCountRaw": 2,    "firstOpenAt": "2026-08-29T09:04:11.000Z",    "lastOpenAt": "2026-08-30T07:42:55.000Z",    "firstClickAt": "2026-08-29T09:05:02.000Z",    "lastClickAt": "2026-08-29T09:05:02.000Z",    "recipients": [      {        "email": "[email protected]",        "kind": "to",        "attributed": true,        "openCount": 3,        "clickCount": 1,        "firstOpenAt": "2026-08-29T09:04:11.000Z",        "lastOpenAt": "2026-08-30T07:42:55.000Z",        "firstClickAt": "2026-08-29T09:05:02.000Z",        "lastClickAt": "2026-08-29T09:05:02.000Z"      }    ],    "links": [      {        "id": "lnk_4f0a1c8d29b74e6fa3c05d17",        "url": "https://acme.com/invoices/42",        "label": "View invoice",        "clickCount": 1,        "clickCountRaw": 2      }    ]  }

opens と clicks はそのメッセージに適用された設定、opened と clicked は実際に起きたことです。openCount は閲覧の回数、openCountRaw は取得の回数を数えます。その差（ここでは 4）はスキャナーやプライバシープロキシによるもので、ログと合計値の差が説明不能にならず検証できるように残されています。誰かを名指しする前に読むべきフィールドは attributable です。false は、その閲覧がリスト全員に送られた同一のコピー上で起きたことを意味し、それ以降の特定の受信者についてのあらゆる記述は推測にすぎません。

source は送信元の面を示します。この API 経由の送信は api、アプリ自身が送ったものはすべて composer です。後者では sendId が null になり、だからこそトラッキング id が存在します。

{    "object": "tracking_stats",    "tracked": 128,    "trackedForOpens": 128,    "trackedForClicks": 47,    "opened": 91,    "clicked": 34,    "openRate": 71.1,    "clickRate": 72.3,    "totalOpens": 240,    "totalClicks": 52,    "machineOpens": 173,    "medianTimeToOpenSeconds": 2714,    "byDay": [{ "day": "2026-08-27", "sent": 12, "opened": 9, "clicked": 3 }],    "topLinks": [{ "url": "https://acme.com/pricing", "label": "See pricing", "clickCount": 18 }],    "clients": [{ "client": "Gmail", "count": 96 }],    "countries": [{ "country": "GB", "count": 71 }]  }

比率は送信メール全体ではなく、トラッキングされたメッセージに対する百分率です。10 通に 1 通をトラッキングしているワークスペースの開封率は、その 10 通についてのものであり、送った全メールで割れば、誰かがトラッキングなしの返信を送るたびに下がってしまいます。5 回開封されたメッセージは、開封された 1 通です。比率はメッセージを数え、合計はヒットを数えます。この 2 つを混同するのが、100% を超える開封率が公表される原因です。

{    "object": "list",    "data": [      {        "object": "open",        "id": "opn_1a7c…",        "trackedMessageId": "tmsg_9c1f7b2e4a5d40b8a3e61d2f",        "recipient": "[email protected]",        "kind": "machine",        "counted": false,        "client": "Apple Mail Privacy Protection",        "device": "unknown",        "os": "macOS",        "country": "GB",        "region": "England",        "city": "London",        "createdAt": "2026-08-29T08:19:11.000Z"      }    ]  }

kind は human、proxy、machine のいずれかで、counted はそれが数値を動かしたかどうかを示します。マシンによるヒットは includeMachine=true を渡さない限り除外されます。これが誠実な既定です。記録しているのは、落とすと説明のつかない欠落が生じるからであって、それがエンゲージメントだからではありません。

• —Apple Mail のプライバシー保護は、誰かが見るかどうかにかかわらず、配信時にすべてのメッセージのすべての画像を取得します。これは User-Agent とネットワークから分類され machine として記録されます。送信から 10 秒以内に届いたものも同様です。人の行動がそれほど速く起きることはないからです。
• —Gmail の画像プロキシは machine ではなく proxy です。誰かがメッセージを表示したので開封は本物ですが、端末・クライアント・位置は知りえません。プロキシはキャッシュもするため、2 回目の閲覧はこちらに届かないことがあります。Gmail 経由の数値は常に下限であり、総数ではありません。
• —同じコピーに対する 30 秒以内の 2 回の取得は、1 回の閲覧とみなされます。プレビューペインの再描画や、スクロールでメッセージが再表示されたときにも画像は再取得されますが、1 時間後の本物の再訪問はきちんと数えられます。
• —受信者を特定するには、人ごとに組み立て直せるだけ小さいメッセージである必要があります。推定サイズ × 受信者数が 8MB 未満に収まらなければなりません。それを超えると 1 つの本文が全員に送られ、そこへのヒットはすべて特定不能になります。
• —クリックがあって開封がないメッセージは、確実に読まれています。画像がブロックされる頻度は、リンクがクリックされない頻度よりはるかに高いからです。2 つのカウンターは足し合わせず、別々に読んでください。
• —リンクのない本文についてクリックのトラッキングを要求しても、何も記録されません。送出されるバイト列はトラッキングなしの送信と同一であり、そうでないと主張する行は何とも整合しません。書き換える本文がないメッセージについても同じです。
• —OpenEmail は、自社ユーザーが読むメールから 1×1 の画像を（自らが送ったピクセルも含めて）取り除き、画像を表示した状態でメッセージが表示されたときに開封自体を記録します。そのヒットはクライアントが OpenEmail の human になります。画像を非表示にしている場合は何も記録されません。

カウントされた開封は email.opened を、カウントされたクリックは email.clicked を、購読中のすべてのエンドポイントに対して発火し、この API を経由したものについては、どちらもそのメッセージ自身のイベント履歴に書き込まれます。スキャナーやプライバシープロキシについてはどちらも発火しません。それらを送れば、分類器が数値から排除するために存在している、まさにそのトラフィックで受信側のログが埋まってしまいます。

ダウンロードリンクとして送られたファイルも同じように報告されます。カウントされたダウンロードは email.downloaded を発火し、同じ履歴に記録されます。同じ分類器がスキャナーやリンクプレビューを排除するため、その数は人の数です。ペイロードはファイルを示す情報（shareId、fileId、filename、mimeType、sizeBytes、url）に加えて、downloadCount、first、downloadedAt と、クリックが持つのと同じクライアント・位置のフィールドを含みます。recipient は常に null、attributed は常に false です。ダウンロードリンクはメッセージの全受信者に対する 1 つの URL なので、ダウンロードを特定の 1 人に結び付けることはできません。

const report = await openemail.tracking.get('msg_c5f21cc6bfec…')const cold = await openemail.tracking.list({ days: 30, opened: false })const stats = await openemail.tracking.getStats({  days: 30,  offsetMinutes: -new Date().getTimezoneOffset(),})

ここでの呼び出しはすべて単なる読み取りで、クライアントはそれぞれを個別に再試行します。get は OpenEmailApiError を投げ、一度もトラッキングされなかったメッセージでは isNotFound が true になります。これは、どこに取り込む場合でも保っておく価値のある区別です。