トランザクションEメール

概要エンドポイント

トランザクションEメール追加オプション（英語）を利用している場合は、領収書、アカウントの更新、利用規約の変更、その他の重要なビジネス取引についてのEメールを専用IPアドレス経由で送信できます。

トランザクションEメールは、主にコンテンツのプロモーションに使用されるマーケティングEメール（英語）と異なり、関係性に基づいたコミュニケーションに使用されます。

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

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

方法 概要 使用例
アプリ内トランザクションEメール HubSpotのEメールエディターを使用して、トランザクションEメールを作成します。

スマートコンテンツ、パーソナライズ、テンプレートなど、標準のHubSpot Eメールと同様のメリットがあります。

アプリ内でトランザクションEメールを設定する方法をご確認ください。		 新しいポリシーのページへのリンクを記載した、ポリシーの更新に関するEメールを顧客に送信する。これはサービスに関する更新情報であってマーケティングEメールではないので、配信設定関連のリンク（CAN-SPAMリンクなど）を含める必要はありません。カスタムプロパティーや外部システムに含まれる情報を使用する必要もありません。
SMTP API
独自のサイトまたはアプリからトランザクションEメールを送信して、Eメールのパフォーマンスを追跡したり、HubSpot内にコンタクト情報を作成したりします。コンタクト情報を作成できるかどうかは、SMTPトークンの作成に基づいています。

詳細については後述のSMTP APIセクションをご確認ください。

 別のトランザクションEメールシステムからアカウント登録の確認Eメールを送信した上で、Eメールのパフォーマンスを追跡し、HubSpot内にコンタクトを作成する。
1回送信API アプリ内トランザクションEメールとSMTP APIの組み合わせです。

HubSpotのEメールエディターを使用してトランザクションEメールを作成し、API経由でHubSpotに送信できるカスタム外部トークンをEメールに追加します。

詳細については後述の1回送信APIセクションをご確認ください。		 HubSpotを使用して、領収書Eメールを顧客に送信する。このEメールは購入が行われるとトリガーされ、別のシステムからのカスタム値（購入品目、合計購入金額など）を渡します。さらに、このEメールのパフォーマンスをHubSpotで追跡します。

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

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トークンを作成するには、/marketing/v3/transactional/smtp-tokens/にPOSTリクエストを送信します。

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

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

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

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

トークンが作成されたら、idとpasswordの値を使用して、HubSpotのSMTPサーバーにログインできます。

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

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

SMTPトークンを取得する

API経由でトークンデータを取得する方法を以下に示します。

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

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

campaignNameまたはemailCampaignIdのパラメーターもリクエストに含める必要があります。リクエストの詳細については、この記事の上部の［エンドポイント］タブでご確認いただけます。

レスポンスの詳細

レスポンスには、最上位のフィールドとしてresultsとpagingが含まれます。

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

単一のSMTP APIトークンの照会

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

レスポンスの詳細

レスポンスには、以下の要素から成るSmtpApiTokenViewが含まれます。

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

 

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

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

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

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

レスポンスには、以下の要素から成るSmtpApiTokenViewが含まれます。

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

トークンを削除する

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

レスポンスに含まれるコンテンツはありません。

 

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メールテンプレートを作成して公開する

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

まず、HubSpot上でEメールを設定します。Eメールが作成されたら、APIリクエストの本文で受信者の詳細（Eメールテンプレートに設定済みのコンタクトやカスタムプロパティーを含む）を設定できます。APIリクエストを行う前に、EメールのIDが必要です。

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

email-id-for-drafted-single-send-api-email

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

Screen Shot 2020-04-15 at 1.00.37 PM

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

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

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

レスポンスには以下のフィールドが含まれます。

    • requestedAt：送信がリクエストされた時刻のタイムスタンプ。
  • status：送信リクエストのステータス。PENDING、PROCESSING、CANCELED、COMPLETEがあります。

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

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

  • emailId
  • message
  • contactProperties
  • customProperties

emailId

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

メッセージ

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

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

  • to：Eメールの受信者。
  • from：Eメールの「From」ヘッダー。送信者名は、"from":"送信者名 <sender@hubspot.com>"の形式で定義できます。
  • sendId：特定の送信のID。所定のsendIdが割り当てられたEメールは、アカウントごとに1回だけ送信されます。このフィールドは、Eメールの重複送信を防止する目的で含めることができます。
  • replyTo：Eメールの「Reply-To」ヘッダーの値のJSONリスト。
  • cc：CCとして送信するEメールアドレスのJSONリスト。
  • bcc：BCCとして送信するEメールアドレスのJSONリスト。

contactProperties

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

name-token-in-template-for-transactional-email

これらのプロパティーは、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メールテンプレートの内容を次のようにレンダリングします。

example-transactional-email-with-customProperties-array

Eメール送信のステータスを問い合わせる

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

レスポンスには以下のフィールドが含まれます。

    • sendResult：Eメールの送信ステータスを表す列挙フィールド。値については後述します。
    • requestedAt：送信がリクエストされた時刻のタイムスタンプ。
  • startedAt：送信の処理が開始された時刻のタイムスタンプ。
  • completedAt：送信が完了した時刻のタイムスタンプ。
  • statusId：送信のステータスを問い合わせる際に使用できる識別子。
  • status：送信リクエストのステータス。PENDING、PROCESSING、CANCELED、COMPLETEがあります。
  • eventId：送信された場合、送信イベントの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：以前この受信者にバウンスが発生したため、送信ロジックに基づき送信が行われませんでした。
  • PREVIOUS_SPAM：この受信者は以前に同様のEメールをスパム扱いにしました。
  • INVALID_FROM_ADDRESS：送信元アドレスが無効です。
  • MISSING_CONTENT：emailIdが無効か、emailIdが1回送信用として設定されていないEメールと一致します。
  • MISSING_TEMPLATE_PROPERTIES：リクエストとして送信したcustomPropertiesに含まれていないプロパティーが、テンプレートに設定されています。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。