最終更新日: 2025年8月22日

Run in Postman

 EメールエンゲージメントAPIを使用して、CRMレコードのEメールを記録および管理できます。Eメールアクティビティーは、HubSpot内で、またはEメールAPIを使用してログを記録できます。 この記事では、APIを使用したEメールの基本的な管理方法を説明します。利用可能な全てのエンドポイントとそれぞれの要件については、リファレンスドキュメントでご確認いただけます。

​
Eメールを作成する

Eメールエンゲージメントを作成するには、POSTリクエストを/crm/v3/objects/emailsに送信します。 リクエスト本文で、propertiesオブジェクト内にEメールの詳細を追加します。また、associationsオブジェクトを追加して、新しいEメールを既存のレコード（コンタクト、会社など）に関連付けることもできます。

​
プロパティー

Propertiesオブジェクトには、次のフィールドを含めることができます。
フィールド説明
hs_timestamp必須。このフィールドは、Eメールの作成時刻を記録し、レコードタイムラインでのそのEメールの表示位置を決定します。ミリ秒単位またはUTC形式のUnixタイムスタンプを使用できます。
hubspot_owner_idEメールに関連付けられている所有者のID。このフィールドにより、レコードタイムラインにEメール作成者として表示されるユーザーが決まります。
hs_email_directionEメールが送信された方向。指定できる値は次の通りです。EMAIL：BCCアドレスを使用してEメールをCRMから送信したか、CRMに送信して記録された場合。INCOMING_EMAIL：送信して記録されたEメールに返信するEメールの場合。FORWARDED_EMAIL：CRMに転送したEメールの場合。
hs_email_htmlCRMレコードから送信された場合のEメールの本文。
hs_email_statusEメールの送信ステータス。指定可能な値は、BOUNCED、FAILED、SCHEDULED、SENDING、SENTのいずれかです。
hs_email_subject記録されたEメールの件名行。
hs_email_textEメールの本文。
hs_attachment_idsEメールの添付ファイルのID。複数の添付ファイルIDはそれぞれセミコロンで区切られます。
hs_email_headersEメールのヘッダー。このプロパティーの値は、特定の読み取り専用Eメールプロパティーに自動的に入力されます。詳しくは後述のEメールヘッダーを設定する方法をご確認ください。
Eメールエンゲージメントを一括で作成する方法については、リファレンスドキュメントをご参照ください。

​
読み取り専用プロパティー

読み取り専用のEメールプロパティーもあり、HubSpotによって自動的に入力されます。以下の表のプロパティーは全てhs_email_headers値から自動的に入力されます。
フィールド説明
hs_email_from_emailEメール送信者のEメールアドレス。
hs_email_from_firstnameEメール送信者の名。
hs_email_from_lastnameEメール送信者の姓。
hs_email_to_emailEメール受信者のEメールアドレス。
hs_email_to_firstnameEメール受信者の名。
hs_email_to_lastnameEメール受信者の姓。
注: Eメールヘッダーを取得する際に、FromとSenderの両方に値があることに気が付かれると思います。多くの場合、これらは同じ値ですが、Senderは実際のEメールの送信元を示すため、値が異なることがあります。例えば、EメールエイリアスからEメールが送信される場合、Fromの値はユーザーの実際のEメールアドレスを表し、Senderの値はEメールエイリアスを表します。

​
Eメールヘッダーを設定する

ヘッダーによって自動的に読み取り専用プロパティーが入力されるため、Eメールヘッダーを手動で設定する必要がある場合も考えられます。hs_email_headers値を設定するには、次のデータを含むJSONエスケープ文字列を使用します。 
//Example data
{
  "from": {
    "email": "from@domain.com",
    "firstName": "FromFirst",
    "lastName": "FromLast"
  },
  "to": [
    {
      "email": "ToFirst ToLast<to@test.com>",
      "firstName": "ToFirst",
      "lastName": "ToLast"
    }
  ],
  "cc": [],
  "bcc": []
}
例えば、Eメールを作成するリクエストは次のようになります。 
//Example request body
{
  "properties": {
    "hs_timestamp": "2019-10-30T03:30:17.883Z",
    "hubspot_owner_id": "47550177",
    "hs_email_direction": "EMAIL",
    "hs_email_status": "SENT",
    "hs_email_subject": "Let's talk",
    "hs_email_text": "Thanks for youremail",
    "hs_email_headers": "{\"from\":{\"email\":\"from@domain.com\",\"firstName\":\"FromFirst\",\"lastName\":\"FromLast\"},\"sender\":{\"email\":\"sender@domain.com\",\"firstName\":\"SenderFirst\",\"lastName\":\"SenderLast\"},\"to\":[{\"email\":\"ToFirst+ToLast<to@test.com>\",\"firstName\":\"ToFirst\",\"lastName\":\"ToLast\"}],\"cc\":[],\"bcc\":[]}"
  }
}

​
関連付け

Eメールを作成して既存のレコードと関連付けるには、リクエストにassociationsオブジェクトを含めます。例えば、Eメールを作成して取引とコンタクトに関連付ける場合、リクエスト本文は次のようになります。 
// Example request body
{
  "properties": {
    "hs_timestamp": "2019-10-30T03:30:17.883Z",
    "hubspot_owner_id": "11349275740",
    "hs_email_direction": "EMAIL",
    "hs_email_status": "SENT",
    "hs_email_subject": "Let's talk",
    "hs_email_text": "Thanks for your interest let's find a time to connect"
  },
  "associations": [
    {
      "to": {
        "id": 601
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 210
        }
      ]
    },
    {
      "to": {
        "id": 602
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 198
        }
      ]
    }
  ]
}
Associationsオブジェクトには、次のものを含める必要があります。
フィールド説明
toEメールに関連付けるレコード。一意のid値で指定します。
typesEメールとレコードの間の関連付けのタイプ。associationCategoryおよびassociationTypeIdを含めます。デフォルトの関連付けタイプIDはこちらのページに記載されています。または、関連付けAPIを使用して、カスタム関連付けタイプ（ラベル）の値を取得することもできます。

​
Eメールを取得する

Eメールを個別に、または一括で取得することができます。一括取得の方法については、リファレンスドキュメントをご参照ください。 EメールIDを指定して個別にEメールを取得するには、GETリクエストを/crm/v3/objects/emails/{emailId}に送信します。また、リクエストのURLには次のパラメーターを含めることができます。
パラメーター説明
properties返されるプロパティーのカンマ区切りリスト。
associations関連付けられているIDが取得されるオブジェクトタイプのカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。
全てのEメールのリストを取得するには、GETリクエストをcrm/v3/objects/emailsに送信します。リクエストのURLには、次のパラメーターを含めることができます。
パラメーター説明
limitページごとに表示する結果の最大数。
properties返されるプロパティーのカンマ区切りリスト。

​
Eメールを更新する

Eメールを個別に、または一括で更新することができます。EメールIDを指定して個別にEメールを更新するには、PATCHリクエストを/crm/v3/objects/emails/{emailId}に送信します。 リクエスト本文に、更新するEメールプロパティーを含めます。例えば、リクエスト本文は次のようになります。 
// Example request body
{
  "properties": {
    "hs_timestamp": "2019-10-30T03:30:17.883Z",
    "hubspot_owner_id": "11349275740",
    "hs_email_direction": "EMAIL",
    "hs_email_status": "SENT",
    "hs_email_subject": "Let's talk tomorrow",
    "hs_email_text": "Thanks for your interest let's find a time to connect!"
  }
}
HubSpotでは、読み取り専用プロパティーおよび存在しないプロパティーの値が無視されます。プロパティー値をクリアするには、リクエストの本文でプロパティーの空の文字列を渡します。 一括更新の方法については、リファレンスドキュメントをご参照ください。

​
既存のEメールをレコードに関連付ける

Eメールをレコード（コンタクトや、それに関連付けられている会社など）に関連付けるには、PUTリクエストを/crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。リクエストのURLには次のフィールドが含まれます。
フィールド説明
emailIdEメールのID。
toObjectTypeEメールに関連付けるオブジェクトのタイプ（コンタクト、会社など）。
toObjectIdEメールに関連付けるレコードのID。
associationTypeIdEメールと他のオブジェクトとの関連付けタイプを示す一意の識別子。このIDは、数値またはスネークケース（例：email_to_contact）で表すことができます。該当する値は関連付けAPIを介して取得できます。
例えば、リクエストのURLは次のようになります。 https://api.hubspot.com/crm/v3/objects/emails/17691787884/associations/contact/104901/198

​
関連付けを削除する

Eメールとレコードの間の関連付けを削除するには、上記と同じ以下のURLに対してDELETEリクエストを送信します。 /crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

​
レコードでEメールをピン留めする

レコードでEメールをピン留めして、レコードのタイムラインの上部に常に表示されるようにすることができます。ピン留めする前に、Eメールが既にレコードに関連付けられている必要があり、1つのレコードにつき1つのアクティビティーのみをピン留めできます。Eメールをピン留めするには、オブジェクトAPIを介してレコードを作成または更新するときに、hs_pinned_engagement_idフィールドにEメールのidを含めます。詳しくは、会社、コンタクト、取引、チケット、およびカスタムオブジェクトのAPIの使用に関する説明をご参照ください。

​
Eメールを削除する

Eメールをいったん削除すると、完全に削除され、復元することはできません。Eメールを個別に、または一括で削除することができます。 EメールIDを指定して個別にEメールを削除するには、DELETEリクエストを/crm/v3/objects/emails/{emailId}に送信します。 Eメールの削除方法については、リファレンスドキュメントをご参照ください。