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

# トランザクションEメールAPIガイド

export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

[トランザクションEメール追加オプション](https://www.hubspot.com/products/marketing/transactional-email)を利用すると、注文確認、アカウント更新、サービス利用規約の変更や、その他の重要なビジネス取引についてのEメールを専用IPアドレスから送信できます。

トランザクションEメールは、主にコンテンツのプロモーションに使用される[マーケティングEメール](/api-reference/marketing-campaigns-public-api-v3/guide)とは異なり、関係性に基づくコミュニケーションに使用されます。

<Accordion title="スコープ要件">
  <ScopesList
    scopes={[
  'transactional-email'
]}
  />
</Accordion>

## トランザクションEメールの送信方法

トランザクションEメールの実装には、以下の3つの方法があります。

* [アプリ内でトランザクションEメールを設定する](https://knowledge.hubspot.com/marketing-email/send-transactional-emails)
* [SMTP API](#smtp-api)
* [1回送信API](#single-send-api)

| **方法**               | **概要**                                                                                                                                                                                                       | **使用例**                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **アプリ内トランザクションEメール** | HubSpotのEメールエディターを使用してトランザクションEメールを作成します。スマートコンテンツ、パーソナライズ、テンプレートなど、HubSpotの標準Eメールと同様の機能を活用できます。[アプリ内でトランザクションEメールを設定する方法](https://knowledge.hubspot.com/marketing-email/send-transactional-emails)をご確認ください。 | 新しいポリシーページへのリンクを設定した、ポリシーの更新に関するEメールを顧客に送信できます。これはサービスの更新を知らせるEメールであって、マーケティングEメールではないので、配信関連リンク（CAN-SPAMリンクなど）を含める必要はありません。カスタムプロパティーや、外部システムからの情報を使用する必要もありません。 |
| **SMTP API**         | 貴社のサイトまたはアプリからトランザクションEメールを送信し、Eメールのパフォーマンス追跡やHubSpot内でのコンタクト情報の作成が行えます。コンタクト情報を作成するかどうかは、SMTPトークンを作成して設定します。詳細については[後述のSMTP APIセクション](#smtp-api)をご確認ください。                                                   | 別のトランザクションEメールシステムからアカウント登録の確認メールを送信した上で、Eメールのパフォーマンスを追跡し、HubSpot内にコンタクトを作成できます。                                                                                  |
| **1回送信API**          | アプリ内トランザクションEメールとSMTP APIの組み合わせです。HubSpotのEメールエディターを使用してトランザクションEメールを作成し、API経由でHubSpotに送信できるカスタム外部トークンをEメールに追加します。詳細については後述の[「1回送信API」セクション](#single-send-api)をご確認ください。                                      | HubSpotを使用して領収書Eメールを顧客に送信できます。購入が完了した時点でこのEメールがトリガーされ、別のシステムからカスタム値（購入品目、合計購入金額など）を渡します。さらに、このEメールのパフォーマンスをHubSpotで追跡します。                                         |

<Warning>
  **注**: トランザクションEメールのCCに指定されているコンタクトは追跡されず、そのコンタクトのレコードタイムラインにトランザクションEメールは表示されません。
</Warning>

## SMTP API

SMTP APIを使用して送信するトランザクションEメールは、特定の条件（eコマースウェブサイトでの購入の実行など）に基づいて自動的にトリガーされます。このAPIはあらゆる内部システムまたはサードパーティーシステムとの連携に利用可能で、Eメールのトリガーと、HubSpotの外部に保存されているデータ（配送情報、購入価格など）の取り込みに使用できます。Eメールの送信は貴社のシステムから行われますが、HubSpotトラッキングコードでラッピングされるため、[エンゲージメントの追跡と測定](https://knowledge.hubspot.com/marketing-email/analyze-your-marketing-email-campaign-performance)が可能です。

SMTP API経由でEメールを送信するには、SMTP APIトークンを使用してHubSpot SMTPサーバーのログイン資格情報を取得する必要があります。サーバーにログインすると、SMTP経由でEメールを送信できます。SMTP APIトークンをまだ作成していない場合は、最初に[新しいトークンを生成する](#create-a-new-smtp-api-token)必要があります。SMTP APIトークンを作成済みの場合は、[API経由でトークンを取得する方法](#get-existing-smtp-api-tokens)をご確認ください。トークンを取得したら、[HubSpotのSMTPサーバーにログインする方法](#log-in)をご確認ください。

Eメールの\_\_送信元アドレスとして使用するドメインは、[Eメール送信ドメイン](https://knowledge.hubspot.com/marketing-email/manage-email-authentication-in-hubspot)としてHubSpotに接続されている必要があります。SMTP API経由でトランザクションEメールを送信する場合に、貴社のHubSpotアカウントに代わって送信できる権限のないドメインを使用すると、エラーが発生します。

<Warning>
  **注**: SMTP APIの全てのメソッドに、認証用の[OAuthトークン](/apps/legacy-apps/authentication/oauth-quickstart-guide)が必要です。
</Warning>

SMTP APIトークンのパスワードを作成、取得、削除、およびリセットするための以下のメソッドはいずれも、APIではなく[HubSpotアカウント内](https://knowledge.hubspot.com/marketing-email/send-transactional-emails#send-a-transactional-email-using-the-smtp-api)でも実行することができます。

### 新しいSMTP APIトークンを作成する

新しいSMTP APIトークンを作成するには、`POST`リクエストを`/marketing/v3/transactional/smtp-tokens/`に送信します。

リクエストの本文には、以下のプロパティーから成るJSON形式のオブジェクトが必要です。

* `createContact`：Eメールの受信者に対応するコンタクトを作成するかどうかを示します。
* `campaignName`：SMTP APIトークンに関連付けるキャンペーンの名前。

このリクエストに対するレスポンスには、以下の要素から成るSMTPトークンオブジェクトが含まれます。

* `id`：HubSpotのSMTPサーバーにログインするためのユーザー名。
* `createdBy`：トークン作成リクエストを送信したユーザーのEメールアドレス。
* `password`：HubSpotのSMTPサーバーにログインするためのパスワード。
* `emailCampaignId`：トークン作成リクエストで指定した、キャンペーンに割り当てる識別子。
* `createdAt`：トークンの作成時に生成されたタイムスタンプ。
* `createContact`：Eメールの受信者に対応するコンタクトを作成するかどうかを示します。
* `campaignName`：トークンに関連付けられたキャンペーンの名前。

トークンが作成されたら、`id`と`password`の値を使用して[HubSpotのSMTPサーバーにログイン](#log-in)できます。

トークンのパスワードは、作成時にのみ取得できます。パスワードを忘れた場合、または新しいパスワードを設定する場合は、[トークンのパスワードをリセットする](#manage-existing-tokens)必要があります。

### トークンの無効化と有効期限

潜在的なセキュリティーインシデントから開発者を保護するために、HubSpotはGitHubリポジトリーで公開されているSMTP認証トークンをモニタリングし、無効化します。検出されたSMTPトークンは自動的に無効になり、Eメールとアプリ内通知で通知されます。その後は新しいトークンを生成し、連携を更新して、失効したトークンを置き換えることができます。詳細については[トークンの無効化を自動化する方法](/apps/legacy-apps/authentication/oauth-quickstart-guide#refreshing-oauth-tokens)をご確認ください。

![smtpトークン自動無効化バナー](https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/smtp-token-automatic-deactivation-banner.png)

公開APIで生成したSMTP APIトークンの有効期限は12か月です。有効期限を迎えると、自動的に削除されます。[HubSpotアカウント内](https://knowledge.hubspot.com/marketing-email/send-transactional-emails#send-a-transactional-email-using-the-smtp-api)で直接作成されたトークンは、自動的には失効<u>しません</u>。

### SMTPトークンを取得する

ここでは、API経由でトークンデータを取得する方法を説明します。

#### キャンペーンごとにSMTP APIトークンのリストを取得する

キャンペーン名に基づいてトークンのリストを取得するか、キャンペーンIDに基づいて1つのトークンを取得するには、`GET`リクエストを`/marketing/v3/transactional/smtp-tokens`に送信します。

`campaignName`または`emailCampaignId`のパラメーターもリクエストに含める必要があります。リクエストの詳細については、[トランザクションEメールのエンドポイントのリファレンスドキュメント](/api-reference/marketing-transactional-single-send-v3/guide)をご確認ください。

**レスポンスの詳細**

このリクエストに対するレスポンスには、最上位フィールドとして`results`と`paging`が含まれます。

* `results`：以下の要素から成る`SmtpApiTokenView`のコレクション。
  * `id`：HubSpotのSMTPサーバーにログインするためのユーザー名。
  * `createdBy`：トークン作成リクエストを送信したユーザーのEメールアドレス。
  * `emailCampaignId`：トークン作成リクエストで指定した、キャンペーンに割り当てる識別子。
  * `createdAt`：トークンの作成時に生成されたタイムスタンプ。
  * `createContact`：Eメールの受信者に対応するコンタクトを作成するかどうかを示します。
  * `campaignName`：トークンに関連付けられたキャンペーンの名前。
* `paging`：さらに結果をリクエストするための`next.after`フィールドが含まれます。

#### 単一のSMTP APIトークンを照会する

IDに基づいて単一のSMTP APIトークンを照会するには、`GET`リクエストを`/marketing/v3/transactional/smtp-tokens/{tokenId}`に送信します。

##### レスポンスの詳細

このリクエストに対するレスポンスには、以下の要素から成る`SmtpApiTokenView`が含まれます。

* `id`：HubSpotのSMTPサーバーにログインするためのユーザー名。
* `createdBy`：トークン作成リクエストを送信したユーザーのEメールアドレス。
* `emailCampaignId`：トークン作成リクエストで指定した、キャンペーンに割り当てる識別子。
* `createdAt`：トークンの作成時に生成されたタイムスタンプ。
* `createContact`：Eメールの受信者に対応するコンタクトを作成するかどうかを示します。
* `campaignName`：トークンに関連付けられたキャンペーンの名前。

### 既存のトークンを管理する

トークンを作成した後、API経由でパスワードをリセットしたり、トークンを削除したりすることができます。

#### パスワードをリセットする

トークンのパスワードをリセットするには、POSTリクエストを`/marketing/v3/transactional/smtp-tokens/{tokenId}/password-reset`に送信します。

このリクエストに対するレスポンスには、以下の要素から成る`SmtpApiTokenView`が含まれます。

* `id`：HubSpotのSMTPサーバーにログインするためのユーザー名。
* `createdBy`：トークン作成リクエストを送信したユーザーのEメールアドレス。
* `emailCampaignId`：トークン作成リクエストで指定した、キャンペーンに割り当てる識別子。
* `createdAt`：トークンの作成時に生成されたタイムスタンプ。
* `createContact`：Eメールの受信者に対応するコンタクトを作成するかどうかを示します。
* `campaignName`：トークンに関連付けられたキャンペーンの名前。

#### トークンを削除する

単一のSMTP APIトークンを削除するには、DELETEリクエストを`/marketing/v3/transactional/smtp-tokens/{tokenId}`に送信します。

このリクエストに対するレスポンスにコンテンツは含まれません。

### HubSpotのSMTPサーバーにログインする

ここでは、トークンで指定されたユーザー名（`id`）とパスワードを使用してHubSpotのSMTPサーバーにログインする方法を説明します。

* **SMTPホスト名**
  * EUを拠点にしていない場合は、ホスト名として`smtp.hubapi.com`を使用します。
  * EUを拠点にしている場合は、ホスト名として`smtp-eu1.hubapi.com`を使用します。
* **SMTPポート**
  * STARTTLSの場合は、ポート25または587を使用できます。
  * 直接TLSの場合は、ポート465を使用します。
* **SMTPユーザー名**: IDフィールドで指定します。
* **SMTPパスワード**: passwordフィールドで指定します。

## 1回送信API

1回送信APIでは、JSON形式の`POST`リクエストを使用して、HubSpotのEメールツールで作成したテンプレートEメールを送信できます。このAPI経由で送信するEメールは、Eメールアドレスに基づいて自動的にコンタクトレコードに関連付けられます。Eメールアドレスが一致するコンタクトがない場合、そのEメールアドレスのコンタクトが新たに作成されます。Eメールを送信する際にコンタクトを作成しない場合は、[SMTP API](#SMTP-API)を使用してください。

### Eメールテンプレートを作成して公開する

まず、[HubSpot上でEメールを設定](https://knowledge.hubspot.com/marketing-email/send-transactional-emails)します。Eメールを作成したら、APIリクエストの本文で受信者の詳細（Eメールテンプレートに設定済みのコンタクトやカスタムプロパティーを含む）を設定できます。APIリクエストを行う前に、EメールのIDが必要です。

* Eメールを公開せずに下書きのままにしている場合、EメールエディターでURLからEメールIDを取得できます。URLの最後のスラッシュ文字（`/`）の前にある最後の数値がEメールIDです（例：`https://app.hubspot.com/email/{PORTAL_ID}/edit/{EMAIL_ID}/settings`）。

![1回送信APIで送信する下書き中EメールのEメールID](https://www.hubspot.com/hubfs/Knowledge_Base_2023/email-id-for-drafted-single-send-api-email.png)

* Eメールを公開している場合は、Eメールの詳細ページからEメールIDをコピーできます。

![Screen Shot 2020-04-15 at 1.00.37 PM](https://cdn2.hubspot.net/hubfs/53/Screen%20Shot%202020-04-15%20at%201.00.37%20PM.png)

<Warning>
  **注**: HubSpotは、このAPIを介して送信されたHTML/JSONを保存しません。受信者のコンタクトのタイムラインからEメールテンプレートを確認できますが、Eメールの内容を記録したい場合は、EメールにBCCを追加することをお勧めします。
</Warning>

### 1回送信APIを使用してEメールを送信する

1回送信APIを使ってEメールを送信するには、`POST`リクエストを`/marketing/v3/transactional/single-email/send`に送信します。

このリクエストに対するレスポンスには、以下のフィールドが含まれます。

* `requestedAt`：送信がリクエストされた時刻のタイムスタンプ。

* `statusId`：[送信のステータスを照会する](#query-the-status-of-an-email-send)際に使用できる識別子。

* `status`：送信リクエストのステータス。`PENDING`、`PROCESSING`、`CANCELED``COMPLETE`があります。

### リクエストのプロパティー

リクエストの本文には、以下のプロパティーから成るJSON形式のオブジェクトが必要です。

* `emailId`
* `message`
* `contactProperties`
* `customProperties`

#### emailId

`emailId`フィールドには、トランザクションEメールのコンテンツIDを指定します。このIDは、HubSpotのEメールツールで確認できます。

#### message

Messageフィールドは、明示的に変更する項目から成るJSONオブジェクトです。少なくとも`to`フィールドを含める必要があります。

Messageオブジェクトに含まれるフィールドは以下の通りです。

* `to`：Eメールの受信者。
* `from`：Eメールの「From」ヘッダー。送信者名は、`"from":"Sender Name <sender@hubspot.com>"`の形式で定義できます。
* `sendId`：送信のID。同じ`sendId`が割り当てられたEメールがアカウント内で2通以上送信されることはありません。このフィールドは、Eメールの重複送信を防止する目的で追加することができます。
* `replyTo`：Eメールの「Reply-To」ヘッダーの値のJSONリスト。
* `cc`：CCとして送信するEメールアドレスのJSONリスト。
* `bcc`：BCCとして送信するEメールアドレスのJSONリスト。

#### contactProperties

`contactProperties`フィールドは、コンタクトのプロパティー値のJSONマップです。コンタクトの各プロパティー値には、`name`と`value`が含まれます。各プロパティーはコンタクトレコード上に設定され、テンプレートで以下の項目の下に表示されます。

![トランザクションEメールのテンプレート内の名前トークン](https://www.hubspot.com/hubfs/Knowledge_Base_2021/Developer/name-token-in-template-for-transactional-email.png)

これらのプロパティーは、Eメールの送信時にコンタクトのプロパティーを設定する場合に使用します。例えば、領収書メールの送信時に`last_paid_date`プロパティーを設定すると、前回の支払いに関する情報を提供できます。

```json theme={null}
{
  "emailId": 4126643121,
  "message": {
    "to": "jdoe@hubspot.com"
    "sendId": "6"
  },
  "contactProperties": {
    "last_paid_date": "2022-03-01",
    "firstname": "jane"
  }
}
```

#### customProperties

`customProperties`フィールドは、キーと値のプロパティーのJSONマップです。一般的に、これらのプロパティーはEメールを受信するコンタクトではなく、Eメール自体に関連しています。これらのプロパティーは、[ウェブページ形式のEメール](https://knowledge.hubspot.com/marketing-email/create-a-web-version-of-your-marketing-email)にも、コンタクトのタイムライン上のEメールのビューにも表示されません。また、HubSpot上にも保存されず、送信Eメールにのみ含められます。

`customProperties`フィールドの各キーは、`custom`変数に含まれるフィールドの[HubL式](/cms/reference/hubl/overview)を使用して、テンプレート内で参照できます（例：`{{ custom.NAME_OF_PROPERTY }}`）。

例えば、Eメールテンプレートが`purchaseUrl`と`productName`の2つのプロパティーを参照している場合、以下のリクエスト本文によって、これらのプロパティーに関連付ける値を指定できます。

```json theme={null}
{
  "emailId": 4126643121,
  "message": {
    "to": "jdoe@hubspot.com"
    "sendId": "6"
  },
  "customProperties": {
    "purchaseUrl": "https://example.com/link-to-product",
    "productName": "vanilla"
  }
}
```

これにより、Eメールテンプレートでこれらのプロパティーを参照できるようになります。

```html theme={null}
<!doctype html>
<html>
  <p>Congrats on purchasing some of the best ice cream around.</p>
  <a href="{{custom.purchaseUrl}}">{{custom.productName}}</a>
</html>
```

[プログラマブルEメールコンテンツ](/cms/start-building/features/data-driven-content/hubdb/video)で`customProperties`フィールドを使用する場合、このフィールドの値としてサポートされるのは配列のみです。Eメールテンプレートでは[HubL式](/cms/reference/hubl/overview)を使用して、`customProperties`フィールドで定義されたアイテムを参照できます（[forループ](/cms/reference/hubl/loops)を使用してリスト内の各アイテムをレンダリングするなど）。例えば、リクエスト本文に含めた`customProperties`が以下のJSONスニペットのように構成されているとします。

```json theme={null}
{
  "emailId": 4126643122,
  "message": {
    "to": "jdoe@hubspot.com"
    "sendId": "7"
  },
  "customProperties": {
    "exampleArray": [
      {"firstKey": "someValue", "secondKey": "anotherValue"},
      {"firstKey": "value1", "secondKey": "value2" }
    ]
  }
}
```

この場合、以下のHubLコードを使用して`exampleArray`の各項目の値を参照できます。

```html theme={null}
<!doctype html>
<html>
  <p>Thanks for your recent purchase! Here are the details of the items you'll be receiving:</p>
  <ul>
    {% for item in custom.exampleArray %}
    <li>First key: {{ item.firstKey }}, Second key: {{item.secondKey}}</li>
    {% endfor %}
  </ul>
</html>
```

送信されたトランザクションEメールでは、関連付けられたプログラマブルEメールテンプレートの内容が以下のようにレンダリングされます。

![customProperties配列を含むトランザクションEメールのサンプル](https://www.hubspot.com/hubfs/Knowledge_Base_2021/Developer/example-transactional-email-with-customProperties-array.png)

### Eメール送信のステータスを照会する

Eメール送信のステータスを調べるには、`GET`リクエストを`https://api.hubapi.com/marketing/v3/email/send-statuses/{statusId}`に送信します。

このリクエストに対するレスポンスには、以下のフィールドが含まれます。

* `sendResult`：Eメールの送信ステータスを表す列挙フィールド。使用される値については[後述](#sendresult)します。

* `requestedAt`：送信がリクエストされた時刻のタイムスタンプ。

* `startedAt`：送信の処理が開始された時刻のタイムスタンプ。

* `completedAt`：送信が完了した時刻のタイムスタンプ。

* `statusId`：送信のステータスを照会する際に使用できる識別子。

* `status`：送信リクエストのステータス。`PENDING`、`PROCESSING`、`CANCELED``COMPLETE`があります。

* `eventId`：Eメールが送信された場合、送信イベントのIDと送信時に生成されたタイムスタンプ。

#### sendResult

`sendResult`はEメールの送信試行の結果を反映する列挙フィールドです。使用される値は以下の通りです。

* `SENT`：Eメールが正常に送信されました。
* `QUEUED`：Eメールがキューに追加され、キューによる送信処理を待機中です。
* `PORTAL_SUSPENDED`：[利用規定](https://legal.hubspot.com/acceptable-use)の違反により、このHubSpot利用企業のEメールは停止されています。
* `INVALID_TO_ADDRESS`：受信者のアドレスが無効です。このエラーは、役割ベースの先頭文字（`abuse`、`no-reply`、`noreply`、`root`、`spam`、`security`、`undisclosed-recipients`、`unsubscribe`、`inoc`、`postmaster`、`privacy`）のいずれかがメールアドレスに含まれるメールを送信しようとした場合にも発生します。
* `BLOCKED_DOMAIN`：現時点ではドメインがHubSpotからのEメールを受信できません。
* `PREVIOUSLY_BOUNCED`：以前この受信者へのEメールにバウンスが発生したため、送信ロジックに基づき送信が行われませんでした。
* `PREVIOUS_SPAM`：この受信者は以前に同様のEメールをスパムに分類しました。
* `INVALID_FROM_ADDRESS`：送信者アドレスが無効です。
* `MISSING_CONTENT`：`emailId`が無効か、`emailId`が1回送信用として設定されていないEメールと一致します。
* `MISSING_TEMPLATE_PROPERTIES`：リクエストとして送信した`customProperties`に含まれていないプロパティーが、テンプレートに設定されています。