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

トランザクションEメール追加オプションを利用すると、注文確認、アカウント更新、サービス利用規約の変更や、その他の重要なビジネス取引についてのEメールを専用IPアドレスから送信できます。トランザクションEメールは、主にコンテンツのプロモーションに使用されるマーケティングEメールとは異なり、関係性に基づくコミュニケーションに使用されます。

スコープ要件

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

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

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

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

SMTP API

SMTP APIを使用して送信するトランザクションEメールは、特定の条件（eコマースウェブサイトでの購入の実行など）に基づいて自動的にトリガーされます。このAPIはあらゆる内部システムまたはサードパーティーシステムとの連携に利用可能で、Eメールのトリガーと、HubSpotの外部に保存されているデータ（配送情報、購入価格など）の取り込みに使用できます。Eメールの送信は貴社のシステムから行われますが、HubSpotトラッキングコードでラッピングされるため、エンゲージメントの追跡と測定が可能です。 SMTP API経由でEメールを送信するには、SMTP APIトークンを使用してHubSpot SMTPサーバーのログイン資格情報を取得する必要があります。サーバーにログインすると、SMTP経由でEメールを送信できます。SMTP APIトークンをまだ作成していない場合は、最初に新しいトークンを生成する必要があります。SMTP APIトークンを作成済みの場合は、API経由でトークンを取得する方法をご確認ください。トークンを取得したら、HubSpotのSMTPサーバーにログインする方法をご確認ください。 Eメールの__送信元アドレスとして使用するドメインは、Eメール送信ドメインとしてHubSpotに接続されている必要があります。SMTP API経由でトランザクションEメールを送信する場合に、貴社のHubSpotアカウントに代わって送信できる権限のないドメインを使用すると、エラーが発生します。

注: SMTP APIの全てのメソッドに、認証用のOAuthトークンが必要です。

SMTP APIトークンのパスワードを作成、取得、削除、およびリセットするための以下のメソッドはいずれも、APIではなくHubSpotアカウント内でも実行することができます。

新しい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サーバーにログインできます。トークンのパスワードは、作成時にのみ取得できます。パスワードを忘れた場合、または新しいパスワードを設定する場合は、トークンのパスワードをリセットする必要があります。

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

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

公開APIで生成したSMTP APIトークンの有効期限は12か月です。有効期限を迎えると、自動的に削除されます。HubSpotアカウント内で直接作成されたトークンは、自動的には失効しません。

SMTPトークンを取得する

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

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

キャンペーン名に基づいてトークンのリストを取得するか、キャンペーンIDに基づいて1つのトークンを取得するには、GETリクエストを/marketing/v3/transactional/smtp-tokensに送信します。 campaignNameまたはemailCampaignIdのパラメーターもリクエストに含める必要があります。リクエストの詳細については、トランザクションEメールのエンドポイントのリファレンスドキュメントをご確認ください。 レスポンスの詳細 このリクエストに対するレスポンスには、最上位フィールドとして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を使用してください。

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

まず、HubSpot上でEメールを設定します。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）。

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

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

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

1回送信APIを使ってEメールを送信するには、POSTリクエストを/marketing/v3/transactional/single-email/sendに送信します。このリクエストに対するレスポンスには、以下のフィールドが含まれます。

requestedAt：送信がリクエストされた時刻のタイムスタンプ。
statusId：送信のステータスを照会する際に使用できる識別子。
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メールのテンプレート内の名前トークン

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

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

customProperties

customPropertiesフィールドは、キーと値のプロパティーのJSONマップです。一般的に、これらのプロパティーはEメールを受信するコンタクトではなく、Eメール自体に関連しています。これらのプロパティーは、ウェブページ形式のEメールにも、コンタクトのタイムライン上のEメールのビューにも表示されません。また、HubSpot上にも保存されず、送信Eメールにのみ含められます。 customPropertiesフィールドの各キーは、custom変数に含まれるフィールドのHubL式を使用して、テンプレート内で参照できます（例：{{ custom.NAME_OF_PROPERTY }}）。例えば、EメールテンプレートがpurchaseUrlとproductNameの2つのプロパティーを参照している場合、以下のリクエスト本文によって、これらのプロパティーに関連付ける値を指定できます。

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

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

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

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

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

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

<!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メールのサンプル

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

Eメール送信のステータスを調べるには、GETリクエストをhttps://api.hubapi.com/marketing/v3/email/send-statuses/{statusId}に送信します。このリクエストに対するレスポンスには、以下のフィールドが含まれます。

sendResult：Eメールの送信ステータスを表す列挙フィールド。使用される値については後述します。
requestedAt：送信がリクエストされた時刻のタイムスタンプ。
startedAt：送信の処理が開始された時刻のタイムスタンプ。
completedAt：送信が完了した時刻のタイムスタンプ。
statusId：送信のステータスを照会する際に使用できる識別子。
status：送信リクエストのステータス。PENDING、PROCESSING、CANCELED``COMPLETEがあります。
eventId：Eメールが送信された場合、送信イベントのIDと送信時に生成されたタイムスタンプ。

sendResult

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

SENT：Eメールが正常に送信されました。
QUEUED：Eメールがキューに追加され、キューによる送信処理を待機中です。
PORTAL_SUSPENDED：利用規定の違反により、この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に含まれていないプロパティーが、テンプレートに設定されています。

アカウントと設定

アプリ管理

認証

自動化

CMS

コミュニケーション設定

コミュニケーション

CRM

イベント

ファイル

マーケティング

スケジューラー

Webhook

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

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

SMTP API

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

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

SMTPトークンを取得する

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

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

レスポンスの詳細

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

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

トークンを削除する

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

1回送信API

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

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

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

emailId

message

contactProperties

customProperties

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

sendResult

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

​SMTP API

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

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

​SMTPトークンを取得する

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

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

レスポンスの詳細

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

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

​トークンを削除する

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

​1回送信API

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

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

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

​emailId

​message

​contactProperties

​customProperties

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

​sendResult

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

SMTP API

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

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

SMTPトークンを取得する

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

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

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

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

トークンを削除する

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

1回送信API

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

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

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

emailId

message

contactProperties

customProperties

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

sendResult