> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timothe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Marketing Cloud メールとの連携

> Salesforce Marketing Cloud Email Studio から配信するメールに Turnint AI のリンクを埋め込み、Subscriber 情報を引き継いでエージェント体験へ誘導する方法

Salesforce Marketing Cloud Engagement の Email Studio から配信するメールに Turnint AI のリンクを差し込み、Subscriber 情報（メールアドレス、SubscriberKey、会社名など）を URL の query parameter として引き継ぐことで、ゲートをスキップしたパーソナライズされたエージェント体験へ誘導できます。

<Info>
  Marketing Cloud の CloudPages（フォーム送信）からの誘導は別ドキュメントで解説しています。本ページはメール配信からの導線に特化した内容です。あわせて [Marketing Cloud CloudPages との連携](/ja/get-started/onboarding/marketing-cloud-landing-page) もご参照ください。
</Info>

## フロー

```mermaid theme={null}
flowchart LR
    A["Email Studio 配信"] --> B["AMPscript で URL を組み立て"]
    B --> C["Subscriberがリンクをクリック"]
    C --> D["?email=...&sk=..."]
    D --> E["Turnint AIエージェントページ"]
```

1. Email Studio のメールに、AMPscript または Personalization String を含む Turnint AI の URL を埋め込む
2. 配信時に `%%emailaddr%%` などの変数が Subscriber ごとの値に展開される
3. Subscriber がリンクをクリックすると、Marketing Cloud の Link Wrapping を経由して Turnint AI のポータルに到達する
4. Turnint AI のポータルが query parameter を読み取り、ゲートのフォームフィールドと一致する値を事前入力する
5. ゲートのフォームフィールドと一致するパラメータがあれば入力済み扱いとなり、ゲートの設定で `自動確認` オプションがアクティブの場合はゲートをスキップして自動でセッションを開始する

## 仕組み

### AMPscript と Personalization String

Marketing Cloud のメール本文では、動的な値を埋め込む手段として 2 系統が用意されています。

* **Personalization String** — `%%emailaddr%%` のように `%%fieldname%%` 形式で Subscriber の属性値や送信メタ情報を直接展開する
* **AMPscript** — `%%[ ... ]%%` または `%%=Function()=%%` 形式で、変数代入・条件分岐・関数呼び出しを伴うロジックを記述する

URL のクエリ文字列に Personalization String を直接書くだけでも値置換は行われますが、`@` 記号や日本語などの非 ASCII を安全に渡すには AMPscript の `URLEncode()` でラップするのが安全です。クリックトラッキングを残したい場合は、組み立てた URL を `RedirectTo()` 経由で `<a href>` に注入する必要があります。

### 代表的な Personalization String / Built-in Variables

| 文字列                                        | 値                                    |
| ------------------------------------------ | ------------------------------------ |
| `%%emailaddr%%`                            | Subscriber のメールアドレス                  |
| `%%subscriberkey%%` / `%%_subscriberkey%%` | SubscriberKey（推奨識別子）                 |
| `%%firstname%%` / `%%lastname%%`           | プロファイル属性                             |
| `%%jobid%%`                                | 送信ジョブ ID                             |
| `%%_messagecontext%%`                      | `PREVIEW`（テスト送信）/ `LIVE`（実配信）の判定に使える |

<Info>
  Profile Attribute やプリファレンスとして登録したカスタム属性も、`%%属性名%%` の形式で参照できます。属性名は Setup → Data Management → Profile Management で確認できます。
</Info>

### Turnint AI 側での受け取り

Turnint AI のポータル（`xxx.turnint.site`）は、URL の query parameter のうち、ゲートのフォームフィールドのキーと一致するパラメータを入力済みとして扱います。ゲートに含まれない query parameter はセッションのユーザーデータには保持されません。追加のコンテキストを保持したい場合は、ゲートフィールドとして定義するか、埋め込み時の `data-turnint-context` を使用してください。

詳細な内部仕様（ゲートとの一致ルール、`自動確認` の挙動）は [Marketing Cloud CloudPages との連携 ＞ Turnint AI 側の設定](/ja/get-started/onboarding/marketing-cloud-landing-page#turnint-ai-側の設定) を参照してください。

## 推奨パラメータ

メールから誘導する URL には、以下のパラメータを推奨します。

| パラメータ名      | AMPscript 値                             | 必須 / 任意 | 説明                                                         |
| ----------- | --------------------------------------- | ------- | ---------------------------------------------------------- |
| `email`     | `URLEncode(emailaddr, true, true)`      | 必須      | 見込み顧客の identity key。Turnint AI のバックエンドで人物の突合に使用します         |
| `sk`        | `URLEncode(_subscriberkey, true, true)` | 推奨      | SubscriberKey。EmailAddress と異なり変動しないため、重複検知や結合キーとして安定しています |
| `firstname` | `URLEncode(firstname, true, true)`      | 任意      | パーソナライズ表示／ゲート事前入力                                          |
| `lastname`  | `URLEncode(lastname, true, true)`       | 任意      | 同上                                                         |
| `company`   | `URLEncode(company, true, true)`        | 任意      | 会社名フィールドの事前入力                                              |
| `<カスタム>`    | `URLEncode(Attribute, true, true)`      | 任意      | ゲートのフィールドキーと一致させると事前入力扱いになります                              |

<Note>
  パラメータ名は、Marketing Cloud の Profile Attribute 名や Data Extension の列名ではなく、Turnint AI のゲートフィールドキーと揃えてください。
</Note>

## URL 組み立て例

### 基本形（AMPscript で URL を構築 → `RedirectTo()` で href に注入）

メール本文の HTML エディタに AMPscript ブロックを置き、`RedirectTo()` でラップしたリンクを記述します。

```
%%[
  /* 動的な URL を組み立てる */
  SET @email   = URLEncode(emailaddr, true, true)
  SET @subkey  = URLEncode(_subscriberkey, true, true)
  SET @company = URLEncode(company, true, true)

  SET @url = Concat(
    "https://xxx.turnint.site/decks/xxx",
    "?email=",   @email,
    "&sk=",      @subkey,
    "&company=", @company,
    "&autoconfirm=true",
    "&utm_source=mc&utm_medium=email"
  )
]%%
<a href="%%=RedirectTo(@url)=%%">AI コンシェルジュに相談する</a>
```

<Note>
  動的に組み立てた URL を `<a href>` に直接書くと、Marketing Cloud のクリックトラッキング対象から外れてレポートに数値が出ません。**動的な href には必ず `RedirectTo()` を噛ませて**ください。
</Note>

### 暗号化 URL を経由するパターン（`CloudPagesURL()`）

メール本文の URL に PII を平文で乗せたくない場合は、`CloudPagesURL()` で暗号化された `?qs=...` 形式のリンクを生成し、CloudPage 側で復号して Turnint へ橋渡しする構成を取ります。

```
%%[
  /* CloudPage ID = 123 に email と sk を暗号化して渡す */
  SET @cpUrl = CloudPagesURL(123, "email", emailaddr, "sk", _subscriberkey)
]%%
<a href="%%=RedirectTo(@cpUrl)=%%">AI コンシェルジュに相談する</a>
```

CloudPage 側では [Marketing Cloud CloudPages との連携 ＞ C. AMPscript で受信パラメータから動的リダイレクト URL を生成](/ja/get-started/onboarding/marketing-cloud-landing-page#c-ampscript-で受信パラメータから動的リダイレクト-url-を生成) のスニペットで `RequestParameter()` により復号し、Turnint AI へリダイレクトします。

### 変数が空のときのフォールバック

Personalization String は値が未設定の Subscriber に対して空文字列に展開されます。テスト送信用の Subscriber や、プロファイル未登録の連絡先で URL が破損するのを防ぐには、AMPscript の `Empty()` で防御してください。

```
%%[
  SET @email = emailaddr
  IF Empty(@email) THEN
    /* テスト送信用などのフォールバック */
    SET @email = "anonymous@turnint.ai"
  ENDIF

  SET @url = Concat(
    "https://xxx.turnint.site/decks/xxx",
    "?email=", URLEncode(@email, true, true),
    "&autoconfirm=true"
  )
]%%
<a href="%%=RedirectTo(@url)=%%">登録する</a>
```

ただし `email` のような identity key にダミー値を設定したリンクが本番に流れると別人として識別されます。フォールバック付与は **テスト配信時のみ**にとどめるか、`%%_messagecontext%%` で本番分岐してください。

```
%%[
  IF _messagecontext == "PREVIEW" THEN
    SET @email = "preview@turnint.ai"
  ELSE
    SET @email = emailaddr
  ENDIF
]%%
```

## Email Studio への組み込み手順

### Content Builder のメールテンプレートに AMPscript を配置する

1. Email Studio → Content → Content Builder で対象のメールを開く
2. レイアウトに **HTML** または **Free Form** ブロックを追加する
3. 上記の AMPscript スニペットをそのまま貼り付け、`https://xxx.turnint.site/decks/xxx` を実際のエージェントページ URL に置き換える
4. プレビュー機能で実際の Subscriber を選び、`%%=RedirectTo(@url)=%%` が正しい URL に展開されているか、リンク先のクエリストリングが意図どおりかを確認する
5. テスト送信を自分宛に行い、リンクをクリックして `自動確認` によるゲートスキップ動作を検証する

### 全リンクへの UTM 自動付与

特定のキャンペーンやチャネル識別子をすべての配信リンクに一律で付与したい場合は、**Setup → Data Management → Parameter Management** で `utm_source=mc` などのパラメータを定義してください。AMPscript ブロック内で個別に書く必要がなくなり、運用ミスを減らせます。

### Sender Authentication Package（SAP）と独自ドメイン

Marketing Cloud のクリックトラッキングが有効な場合、リンクは既定で `click.exct.net` を経由します。`click.example.com` のような独自サブドメインに変更したい場合は SAP の契約と DNS 設定が必要です。受信側のメールセキュリティスキャンや迷惑メール判定の信頼性が向上します。

## ハマりやすい注意点

* **`<form>` 直接埋め込み不可** — Outlook（デスクトップ）/ Gmail / Yahoo Mail はセキュリティ上の理由から `<form>` `<input>` `<button>` 等のフォーム要素を無効化しています。メール本文には CTA リンクのみ置き、Turnint のゲート（または CloudPage 経由）で入力させる構成を取ってください
* **動的 href には必ず `RedirectTo()`** — `<a href="%%=v(@url)=%%">` のように直接変数を展開すると、Marketing Cloud がメール本文に存在しない URL とみなしクリックトラッキングから外れます。`RedirectTo()` で必ずラップしてください
* **二重 URL エンコード禁止** — `URLEncode(@val, true, true)` を施した値を、さらに `encodeURIComponent` 等で再エンコードしないでください。`%40` が `%2540` になり Turnint 側でメールアドレスとして扱えなくなります
* **SubscriberKey と EmailAddress の使い分け** — EmailAddress はライフサイクルの中で変動するため、重複検知や結合キーには SubscriberKey を推奨します。Salesforce 公式も SubscriberKey と Contact Key をイコールで運用することを推奨しています
* **テスト送信時のプロファイル空** — テスト送信用 Subscriber のプロファイル属性が未設定の場合、Personalization String が空展開されてリンクが破損します。Default Value 設定または `Empty()` ガードで防御してください
* **クリックトラッキングのリダイレクト** — Marketing Cloud の Link Wrapping によりリンクは `click.exct.net`（または SAP のカスタムドメイン）経由になります。最終的に Turnint AI には正しく query parameter が渡りますが、メールクライアントのリンクプレビューでは中間 URL が見える点に留意してください
* **メールクライアント側のリンク改変** — Microsoft Defender Safe Links や社内プロキシによる URL 改変で、query parameter が消失したり追加情報が混ざる可能性があります。受信環境で再現する場合は環境固有の挙動として確認してください

## セキュリティ配慮

### email を URL に含めることの設計上の整理

Turnint AI では、ユーザー識別のために `email` を URL の query parameter として渡すことを推奨しています。一見すると平文の連絡先情報を URL に載せることに抵抗を感じるかもしれませんが、この設計は次の前提に基づいています。

* Marketing Cloud からのメール配信は TLS で行われ、クリックトラッキング経由のリダイレクトサーバーも Marketing Cloud の信頼境界内にあります
* Turnint AI のバックエンドでは、`email` は人物 / コンタクトとの突合に用いるための受け渡しが必要です（識別に使われるキーは `name` `email` `phone` `company` `role` の 5 種に限定されています）
* 平文の URL 露出を避けたい場合は、上記の `CloudPagesURL()` を使った暗号化 URL を経由する設計に切り替えられます

### Referrer-Policy と外部リンクの取り扱い

Turnint AI のポータル URL には `email` などが含まれるため、ポータルページから外部サイトへ遷移する際、Referer ヘッダ経由でこれらの値が漏洩する懸念があります。エージェントセッション中はアウトバウンドリンクを設けない設計が前提のため通常は問題になりませんが、エージェントの応答に外部リンクを含める設計を採用する場合は、ポータルの HTML レスポンスに `Referrer-Policy: strict-origin-when-cross-origin` を最低ライン、より厳格な `strict-origin` または `same-origin` を望ましい設定として検討してください。

### Link Wrapping によるクリックトラッキング経由の URL 改変

Marketing Cloud のクリックトラッキングが有効な場合、リンクは中間 URL を経由します。Turnint AI への最終的な query parameter は保持されますが、社内プロキシやメールセキュリティゲートウェイによる URL 改変で、リンクが破壊されたり余分なパラメータが追加されるケースが稀にあります。重要な配信の前にはテストアカウントで実配信検証を行ってください。

## 関連ドキュメント

* [Salesforce CRM 連携](/ja/integrations/crm.salesforce) — セッションデータの Sales / Service Cloud への自動同期
* [トラッキングパラメータの自動保持](/ja/integrations/tracking-params) — UTM パラメータや広告クリック ID の自動引き継ぎ
* [ウェブフック連携](/ja/integrations/webhook) — セッションデータの外部システムへのリアルタイム同期