# メール配信イベントテーブル

Engage Studioは、Treasure Data CDP内でマーケターが効果的なメールキャンペーンを作成・管理するために設計された強力な機能です。効果的なメールマーケティングの重要な側面は、パフォーマンスを追跡する能力です。Engage Studioは、詳細なメールメトリクスを自動的に収集することで、**メール配信パフォーマンスインサイト**を提供します。
これらの貴重なメールメトリクスは、使用する各メールドメイン用に専用のTreasure Dataテーブルに自動的に保存されます。このテーブルを使用すると、メール送信の結果を詳細なレベルで分析できます。

メールパフォーマンスデータは、Treasure アカウントの以下の場所に保存されます。

* **Database:** `delivery_email_<your email domain>`
* **Table:** `events`


**メールパフォーマンス（**`events`**）テーブルのスキーマ**

`events`テーブルには、メールキャンペーン中に発生する各イベントに関する詳細情報をキャプチャするさまざまな列が含まれています。このテーブルのスキーマには次のフィールドが含まれます。

* `time` (int): `delivery_timestamp`と同等で、時刻を表します。
* `email_sender_id` (string): 送信者のID。
* `email_domain_id` (string): メールドメインのID。
* `email_domain` (string): 送信に使用されたメールドメイン。
* `message_id` (string): 送信リクエストが成功した際にAmazon SESによってメッセージに割り当てられた一意のID。これはメッセージが送信されたときにAmazon SESが返したIDです。なお、Amazon SESはこのIDを`mail`オブジェクトの`commonHeaders`にも含めます。
* `email_template_id` (string): メッセージに使用されたEmail Template ID。このIDは、Engage Studioでメールテンプレートを編集する際のURLパスで確認できます。
* `from` (string): FROMメールアドレス。
* `to` (string): 受信者のTOメールアドレス。これは元のメールの受信者としてリストされているメールアドレスの1つです。
* `to_plain_address` (string): 元々表示名が含まれていた場合でも、シンプルな形式の受信者のメールアドレス。
* `subject` (string): メールの件名。これは`mail`オブジェクトの`commonHeaders`で確認できます。
* `timestamp` (string): 元のメッセージが送信された日時（ISO8601形式）。
* `event_type` (string): 発生したイベントのタイプを示す重要なフィールド。このフィールドは、送信された各メールのさまざまな結果を説明します。
* `delivery_reporting_mta` (string): 配信のMail Transfer Agent（MTA）アドレス。Amazon SESでは、これはメールを送信したSESメールサーバーのホスト名です。
* `delivery_smtp_response` (string): 配信のMTAログ。これは、Amazon SESからのメールを受け入れたリモートISPからのSMTP応答メッセージです。
* `delivery_processing_time_millis` (long): 配信処理にかかった時間（ミリ秒）。これは、Amazon SESがリクエストを受け入れてから受信者のサーバーにメッセージを渡すまでの時間です。
* `delivery_timestamp` (string): メールが配信された時刻。
* `open_user_agent` (string): メールが開封されたときに使用されたメールクライアントのUser Agent。
* `open_timestamp` (string): メールが開封された時刻。
* `open_ip_address` (string): 受信者がメールを開封したIPアドレス。
* `click_user_agent` (string): メールがクリックされたときに使用されたメールクライアントのUser Agent。
* `click_timestamp` (string): メールがクリックされた時刻。
* `click_ip_address` (string): 受信者がメールをクリックしたIPアドレス。
* `click_link` (string): 受信者がクリックしたリンクの完全なURL。このフィールドは、どのコンテンツがエンゲージメントを促進するかを理解するための貴重な分析データを提供します。
* `bounce_reporting_mta` (string): バウンスが発生する前に配信を試みたMTAのIPアドレス。
* `bounce_feedback_id` (string): バウンスに関連付けられた一意のID。
* `bounce_timestamp` (string): Bounceとしてマークされた時刻。
* `bounce_subtype` (string): バウンスのサブタイプ。
* `bounce_type` (string): バウンスのタイプ（Undetermined、Permanent、またはTransient）。
* `bounce_recipient_status` (string): DSNのStatusフィールドの値。これは、メッセージの配信ステータスを示す受信者ごとのトランスポート非依存ステータスコードです。
* `bounce_recipient_action` (string): DSNのActionフィールドの値。これは、このレシピエントにメッセージを配信しようとした結果としてReporting-MTAが実行したアクションを示します。
* `bounce_recipient_address` (string): バウンスした元のメールの受信者に関する情報を含むリスト
* `bounce_recipient_diagnostic_code` (string): レポートMTAが発行したステータスコード。これはDSNのDiagnostic-Codeフィールドの値です。このフィールドはDSNに存在しない場合があります（したがってJSONにも存在しません）。
* `delayed_timestamp` (string): 配信遅延が発生した日時（ISO8601形式）。
* `delayed_type` (string): 遅延のタイプ（例：MailboxFull、MessageTooLarge、TransientCommunicationFailure）。
* `delayed_recipient_address` (string): メッセージの配信が遅延した原因となったメールアドレス。
* `delayed_recipient_status` (string): 配信遅延に関連付けられたSMTPステータスコード。これは受信者ごとのトランスポート非依存ステータスコードです。
* `delayed_recipient_diagnostic_code` (string): 受信MTAが提供した診断コード。これは遅延に関する追加情報を提供します。
* `delayed_expiration_time` (string): Amazon SESがメッセージの配信を停止する日時（ISO8601形式）。
* `complaint_timestamp` (string): ISP が苦情通知を送信した、ISO8601 形式 (YYYY-MM-DDThh:mm:ss.sZ) の日時。
* `complaint_feedback_id` (string): 苦情の一意の ID。
* `complaint_user_agent` (string): フィードバックレポートの User-Agent フィールドの値。これは、レポートを生成したシステムの名前とバージョンを示します。
* `complaint_feedback_type` (string): ISP から受け取ったフィードバックレポートの Feedback-Type フィールドの値。これには、フィードバックのタイプが含まれます。
* `complaint_arrival_date` (string): ISO 8601 形式のフィードバックレポートの Arrival-Date または Received-Date フィールドの値 (YYYY-MM-DDThh:mm:ss.sZ)。このフィールドがレポートにない場合もあります (その場合、JSON オブジェクトにも表示されません)。
* `reject_reason` (string): メールが拒否された理由。このフィールドの唯一の値は Bad content です。E メール内のウイルスを Amazon SES で検出したことを意味します。メッセージが拒否されると、Amazon SES はメッセージの処理を停止し、そのメッセージを受信者のメールサーバーに配信しようとしません。
* `failure_error_message` (string): レンダリング失敗に関する詳細情報を提供するメッセージ。
* `custom_event_id` (string): **パフォーマンス計算に使用される任意のキャンペーンID**。この識別子を使用すると、例えばCustomer Journey Orchestration（CJO）シナリオ内でメールキャンペーンを適切に追跡するのに役立ちます。このIDはメールActivationを設定する際に設定されます。
* `test_mode` (boolean): メールがSendTest機能によって送信されたことを示す場合はTrue
* `campaign_id` (string): キャンペーン機能によりメール送信した際のキャンペーンのID
* `campaign_name` (string): キャンペーン機能によりメール送信した際のキャンペーン名


**メールイベントタイプの理解**

`event_type`列は、送信アクティビティの監視とキャンペーンパフォーマンスの理解に不可欠です。送信された各メールの結果を分類します。この列で見つかる可能性のある値とその意味、およびテーブルでキャプチャされる関連情報は次のとおりです。

* **Send** : メール送信リクエストが成功し、Amazon SESが配信を試みます。抑制によって配信が抑制された場合でも、送信としてカウントされます。
* **Delivery** : Amazon SESがメールを受信者のメールサーバーに正常に配信しました。deliveryオブジェクトには、配信の`timestamp`（`delivery_timestamp`）、`processingTimeMillis`（`delivery_processing_time_millis`）、`recipients`、`smtpResponse`（`delivery_smtp_response`）、`reportingMTA`（`delivery_reporting_mta`）、および`remoteMtaIp`が含まれます。
* **Bounce** : 受信者のメールサーバーがメールを拒否したパーマネントまたはトランジェントバウンスを示します。パーマネントバウンスは、将来の送信が成功する可能性が低く、送信者の評判に悪影響を与える可能性があるため、受信者をリストから削除する必要があることを意味します。トランジェントバウンスは、一時的な問題が解決すれば、後で正常に配信される可能性があります。
* **Complaint** : メールは配信されましたが、受信者がスパムとしてマークしました。complaintオブジェクトには、`complainedRecipients`、`timestamp`、`feedbackId`、`complaintSubType`、およびオプションで`userAgent`、`complaintFeedbackType`、およびフィードバックレポートからの`arrivalDate`が含まれます。ほとんどのISPは苦情を申し立てた特定のメールアドレスを編集するため、`complainedRecipients`リストには苦情を発行したドメインの受信者が含まれます。`complaintFeedbackType`は、苦情の理由（例：abuse、fraud、virus）を示すことができます。
* **DeliveryDelay** : 受信トレイが満杯またはトランジェントサーバーの問題など、問題によりメール配信が一時的に遅延しました。delivery delayオブジェクトには、`delayType`（例：MailboxFull、MessageTooLarge）、`delayedRecipients`、`expirationTime`（SESが配信を停止する時刻）、`reportingMTA`、および`timestamp`が含まれます。
* **Open** : 受信者がメールクライアントでメッセージを開封しました。これはHTMLメール用のオープンピクセルトラッキングに依存しています。openオブジェクトには、受信者の`ipAddress`（`open_ip_address`）、`timestamp`（`open_timestamp`）、および`userAgent`（`open_user_agent`）が含まれます。オープントラッキングはHTMLメールでのみ機能することに注意してください。テキストのみのメールクライアントはこのメトリクスを提供しません。
* **Click** : 受信者がメール内の1つまたは複数のリンクをクリックしました。これはクリックトラッキングに依存しており、HTTPS + カスタムドメインをサポートしています。clickオブジェクトには、受信者の`ipAddress`（`click_ip_address`）、`timestamp`（`click_timestamp`）、`userAgent`（`click_user_agent`）、およびクリックされた完全なURLを含む`link`（`click_link`）が含まれます。


# キャンペーントラッキングのための`custom_event_id`の活用

`custom_event_id`列は、個々のメールキャンペーンまたはジャーニーのパフォーマンスを追跡するために特別に設計されています。メールActivationを設定する際、キャンペーンの一意の識別子を`Custom Event ID`パラメータに入力できます。このIDは`events`テーブルに記録され、そのキャンペーン専用のパフォーマンスメトリクス（送信、配信、開封、クリック、バウンスなど）を簡単にフィルタリングして計算できるようになります。これは、Customer Journey Orchestration（CJO）経由でキャンペーンを実行する場合に特に有用です。

`custom_event_id`は基本的なキャンペーントラッキングを提供しますが、Output Column Mapping機能を使用することで、アクティベーションとジャーニーに関する追加のメタデータを取得できます。

# Output Column Mappingによるメタデータ列の追加

## 概要

Output Column Mappingを使用すると、ジャーニーとアクティベーションのメタデータを追加の列としてメール配信イベントテーブルに追加できます。この機能は、ROIダッシュボードレポートや高度なキャンペーン分析に不可欠です。

## 利用可能なメタデータ列

配信イベントに以下のメタデータ列を追加できます：

| 列名 | 説明 |
|  --- | --- |
| `activation_id` | アクティベーション設定の一意の識別子（自動生成） |
| `activation_name` | アクティベーションの人間が読める名前。このフィールドは手動で入力するカスタム値を受け入れます。 |
| `journey_id` | カスタマージャーニーの一意の識別子。Journey Orchestrationワークフローからトリガーされた場合、String Builderで自動入力されます。その他のアクティベーションタイプでは手動で入力できます。ROIダッシュボードに必須。 |
| `journey_stage_id` | ジャーニー内の特定のステージの識別子。このフィールドはカスタム値を受け入れ、String Builderで自動生成できません。 |


## Output Column Mappingの設定方法

### ステップ1：アクティベーション設定を開く

1. **オーディエンススタジオ**に移動し、セグメントを選択します
2. **アクティベーション**に移動します
3. **Treasure Engage**アクティベーションを作成または編集します


### ステップ2：Output Column Mappingを設定する

1. **アウトプットマッピング**セクションまでスクロールします
2. 含めたい各メタデータフィールドについて、**文字列を追加**をクリックします
3. マッピングを設定します：
  - **`activation_id`**の場合：String Builderを使用して自動生成された値を選択します
  - **`activation_name`**の場合：カスタム値を手動で入力します
  - **`journey_id`**の場合：String Builderを使用してジャーニーIDを選択します（Journey Orchestrationアクティベーションで自動的に利用可能）、またはその他のアクティベーションタイプでは手動でカスタム値を入力します
  - **`journey_stage_id`**の場合：カスタム値を手動で入力します（String Builderは利用できません）
4. 出力列名を入力します（一貫性のため、ソースと同じ名前を使用してください）
5. **保存**をクリックします


### ステップ3：イベントテーブルで確認する

アクティベーションが実行されると、メタデータ列が標準の配信イベント列と一緒に`delivery_email_<your_domain>.events`テーブルで利用可能になります。

## メタデータ列のクエリ

`activation_id`、`journey_id`、`journey_stage_id`列はbase32エンコードされた文字列として保存されます。これらの列を人間が読める形式でクエリするには、`from_base32()`と`from_utf8()`関数を使用してデコードします：


```sql
SELECT
  from_utf8(from_base32(activation_id)) AS activation_id_decoded,
  from_utf8(from_base32(journey_id)) AS journey_id_decoded,
  from_utf8(from_base32(journey_stage_id)) AS journey_stage_id_decoded,
  activation_name,
  email_template_id,
  event_type,
  to
FROM
  delivery_email_<your_domain>.events
WHERE
  TD_INTERVAL(time, '-1d', 'JST')
```

`activation_name`列はプレーンテキストで保存されており、デコードは不要です。

## ユースケース：ROIダッシュボード

これらのメタデータ列により、Reporting Agentがメール配信イベントをジャーニーのパフォーマンスや収益データとリンクさせてROIレポートを生成できるようになります。詳細については、[Report for Engage](/ja/products/marketing-cloud/engage-studio/report-for-engage)を参照してください。

ジャーニー固有のフィールド
`journey_id`と`journey_stage_id`列は、Journey Orchestrationワークフローからアクティベーションがトリガーされた場合にのみ入力されます。スタンドアロンアクティベーションの場合、これらのフィールドはNULLになります。

# `td_log_`プレフィックスによる非PIIカスタム識別子列

## 概要

厳格な社内セキュリティポリシーを持つ組織では、メールアドレスなどの生の個人情報（PII）を分析・運用テーブルに保存することが禁止されている場合があります。一方で、そのような組織においても、配信・バウンス・エラー・配信停止の各イベントを顧客レコードに紐付けて分析する必要があります。

このようなユースケースに対応するため、Engage Studioではアクティベーションのアウトプットマッピングで使用できる予約済みフィールド名プレフィックス **`td_log_`** を提供しています。アウトプットマッピングの出力列名が`td_log_`で始まる場合、その列は次のように扱われます。

- メールイベントログテーブルに列として自動的に追加されます。
- アクティベーションコンテキストからマッピングされた値（例：`member_id`や`crm_id`などのプロファイルアトリビュート）で、イベントごとに自動で値がセットされます。


これにより、任意の非PII識別子（内部会員ID、CRM ID、ハッシュ化されたIDなど）を各イベントとともにログに記録でき、分析用テーブルに生のメールアドレスを露出させる必要がなくなります。

## `td_log_*`列が追加されるテーブル

アクティベーションで1つ以上の`td_log_*`アウトプットマッピングを定義すると、設定した列がEngage Studioの3つのイベントテーブルすべてに出現し、値が入力されます。これによりエンドツーエンドでの紐付け分析が可能になります。

- `delivery_email_<your_domain>.events` — 送信、配信、バウンス、苦情、配信遅延、開封、クリック
- `delivery_email_<your_domain>.error_events` — ランタイムエラー、レンダリングエラー
- `delivery_email_<your_domain>.subscription_events` — 配信停止イベント


同一のアクティベーションから発生した各イベントに対し、同じ`td_log_*`列名には同じ値が入ります。これにより、非PII識別子を使って配信・エラー・配信停止のイベントをJOINで紐付けることができます。

## `td_log_*`フィールドの設定方法

### ステップ1：アクティベーション設定を開く

1. **Audience Studio**に移動し、セグメントを選択します。
2. **Activation**に移動します。
3. **Treasure Engage**アクティベーションを作成または編集します。


### ステップ2：`td_log_*`アウトプットマッピングを追加する

1. **Output Mapping**セクションまでスクロールします。
2. **ソース**には、非PII識別子を保持するプロファイルアトリビュート（例：`member_id`）を選択します。
3. **出力列名**には、`td_log_`で始まる名前（例：`td_log_member_id`）を指定します。
4. **Save**をクリックします。


### ステップ3：イベントテーブルで確認する

アクティベーションが実行されると、設定した`td_log_*`列が`events`、`error_events`、`subscription_events`の各テーブルに出現し、マッピングされた識別子の値が各イベント行に入力されます。

## 例：生のメールアドレスを使わないイベント相関分析

アクティベーションのアウトプットマッピングで`member_id` → `td_log_member_id`、`crm_id` → `td_log_crm_id`とマッピングした場合、生の`to`メールアドレスを参照せずに配信・エラー・配信停止を分析できます。


```sql
SELECT
  e.event_type,
  e.td_log_member_id,
  e.td_log_crm_id,
  COUNT(*) AS event_count
FROM
  delivery_email_<your_domain>.events e
WHERE
  TD_INTERVAL(e.time, '-7d', 'JST')
GROUP BY
  e.event_type, e.td_log_member_id, e.td_log_crm_id
```

## 制限とガイドライン

td_log_*フィールドにPIIをマッピングしないでください
Treasure AIは`td_log_*`の値に対してハッシュ化や暗号化、マスキングなどの処理を行いません。生のメールアドレスやその他のPIIを`td_log_*`フィールドにマッピングしないでください。内部会員ID、CRM ID、事前にハッシュ化したIDなどの非PII識別子のみを使用してください。

- **1アクティベーションあたり最大5個の`td_log_*`フィールド。** イベントスキーマを安定させ、列数が過度に増加することを防ぎます。6個目以降のフィールドは通知なしに破棄されます。
- **出力列名はASCII文字（英字、数字、アンダースコア）のみを使用してください。** 非ASCII文字は、予期しないエラーや誤った列マッピングを避けるため無視されます。
- **列名の長さは`td_log_`プレフィックスを含めて256文字までです。**
- **識別子はログに記録されるだけで、メール本文には出力されません。** `td_log_*`にマッピングした値はイベントロギングと分析相関のみに使用され、メール本文や件名には差し込まれません。
- **バックフィルはありません。** `td_log_*`マッピングを設定した後に発生したイベントにのみ新しい列が付与されます。既存のイベントには遡及適用されません。
- **後方互換性あり。** `td_log_*`フィールドが設定されていない場合、すべてのイベントテーブルのスキーマと動作は従来と変わりません。


## オプション：アカウント単位でのPII列の抑制

生のメールアドレスなどの受信者PIIを分析テーブルに保存することを一切禁止する、厳格なPIIデータ保管ポリシーを持つエンタープライズ顧客向けに、Treasure AIではアカウント単位でEngage Studioの3つのイベントテーブル全体のPII列を抑制するオプションを提供しています。このオプションが有効化されると、該当アカウントで発生する新規イベントでは以下の列が`NULL`で記録されます。

- `events`および`error_events`テーブル:
  - `to`
  - `to_plain_address`
  - `subject`
- `events`テーブルのみ:
  - `bounce_recipient_address`
  - `delayed_recipient_address`
  - `open_ip_address`
  - `open_user_agent`
  - `click_ip_address`
  - `click_user_agent`
  - `click_link`
- `subscription_events`テーブルのみ:
  - `profile_identifier_value`


PII列が抑制された状態では、顧客レコードとの相関分析には[上記](#td_log%E3%83%97%E3%83%AC%E3%83%95%E3%82%A3%E3%83%83%E3%82%AF%E3%82%B9%E3%81%AB%E3%82%88%E3%82%8B%E9%9D%9Epii%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E8%AD%98%E5%88%A5%E5%AD%90%E5%88%97)の`td_log_*`非PII識別子を利用してください。

有効化方法
このオプションはTreasure AIアカウント単位で適用され、セルフサービスでは有効化できません。有効化を希望される場合はTreasure AIサポートまでお問い合わせください。設定は有効化後に発生するイベントに対してのみ反映され、既存のイベントは変更されません。