Email

Please note: This API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer TermsDeveloper Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API. For the latest stable version of the engagements API, check out the legacy engagements overview.

Use the email engagement API to log and manage emails on CRM records. You can log email activities either in HubSpot or through the emails API. 

Below, learn the basic methods of managing emails through the API. To view all available endpoints and their requirements, click the Endpoints tab at the top of this article.

Create an email engagement

To create an email engagement, make a POST request to /crm/v3/objects/emails.

In the request body, add email details in a properties object, which can contain the following fields:

Use this table to describe parameters / fields
FieldDescription
hs_timestamp

Required. This field marks the email's time of creation and determines where the email sits on the record timeline. You can use either a Unix timestamp in milliseconds or UTC format. 

hubspot_owner_id

The ID of the owner associated with the email. This field determines the user listed as the email creator on the record timeline.

hs_email_direction

The direction the email was sent in. The value can be EMAILINCOMING_EMAIL, or FORWARDED_EMAIL

hs_email_status

The send status of the email. The value can be BOUNCED, FAILED, SCHEDULED, SENDING, or SENT.

hs_email_subject

The subject line of the logged email. 

hs_email_text

The body of the email. 

hs_email_sender_email

The email address of the email's sender. This field is read only.

hs_email_sender_firstname

The email sender's first name. This field is read only

hs_email_sender_lastname

The email sender's last name. This field is read only.

hs_email_to_email

The email addresses of the email's recipients. This field is read only

hs_email_to_firstname

The first names of the email's recipients. This field is read only

hs_email_to_lastname

The last names of the email recipient. This field is read only.

For example, your request body might look similar to the following:

JSON
// 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"
}
}

Learn more about batch creating email engagements by clicking the Endpoints tab at the top of this article.

Associate emails with records

To associate an email with records, such as a contact and its associated companies, make a PUT request to /crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationType}. The request URL contains the following fields:

Use this table to describe parameters / fields
FieldDescription
emailId

The ID of the email.

toObjectType

The type of object that you want to associate the email with (e.g., contact or company)

toObjectId

The ID of the record that you want to associate the email with.

associationType

The ID of the association type between the email and the other object type. You can retrieve this value through the associations API.

For example, your request URL might look similar to the following:

https://api.hubspot.com/crm/v3/objects/emails/17691787884/associations/contact/104901/198

Remove an association

To remove an association between an email and a record, make a DELETE request to the same URL as above:

/crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationType}

Retrieve emails

You can retrieve emails individually or in bulk. Learn more about batch retrieval by clicking the Endpoints tab at the top of this article.

To retrieve an individual email by its email ID, make a GET request to /crm/v3/objects/emails/{emailId}. You can also include the following parameters in the request URL: 

Use this table to describe parameters / fields
ParameterDescription
properties

A comma separated list of the properties to be returned. 

associations

A comma separated list of objects to you want to retrieve associated record IDs from. 

To request a list of all of emails, make a GET request to crm/v3/objects/emails. You can include the following parameters in the request URL: 

Use this table to describe parameters / fields
ParameterDescription
limit

The maximum number of results to display per page.

properties

A comma separated list of the properties to be returned. 

Update emails

You can update emails individually or in batches. To update an individual email by its email ID, make a PATCH request to /crm/v3/objects/emails/{emailId}

In the request body, include the email properties that you want to update. For example, your request body might look similar to the following:

JSON
// 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 will ignore values for read-only and non-existent properties. To clear a property value, pass an empty string for the property in the request body.

Learn more about batch updating by clicking the Endpoints tab at the top of this article.

Delete emails

You can delete emails individually or in batches, which will add the email to the recycling bin in HubSpot. You can later restore the email from the record timeline.

To delete an individual email by its email ID, make a DELETE request to /crm/v3/objects/emails/{emailId}.

Learn more about batch deleting by clicking the Endpoints tab at the top of this article.


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.