Skip to main content

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, check out the reference documentation.

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. You can also add an associations object to associate your new email with an existing record (e.g., contacts, companies).

In the properties object, you can include the following fields:

FieldDescription
hs_timestampRequired. 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_idThe ID of the owner associated with the email. This field determines the user listed as the email creator on the record timeline.
hs_email_directionThe direction the email was sent in. Possible values include:EMAIL: the email was sent from the CRM or sent and logged to the CRM with the BCC address.INCOMING_EMAIL: the email was a reply to a logged outgoing email. FORWARDED_EMAIL: the email was forwarded to the CRM.
hs_email_htmlThe body of an email if it is sent from a CRM record.
hs_email_statusThe send status of the email. The value can be BOUNCED, FAILED, SCHEDULED, SENDING, or SENT.
hs_email_subjectThe subject line of the logged email.
hs_email_textThe body of the email.
hs_attachment_idsThe IDs of the email's attachments. Multiple attachment IDs are separated by a semi-colon.
hs_email_headersThe email's headers. The value for this property will automatically populate certain read only email properties. Learn how to set email headers.

Learn more about batch creating email engagements by checking out the reference documentation.

There are also some email properties that are read only, which are automatically populated by HubSpot. The properties in the table below are all automatically populated from the hs_email_headers value.

FieldDescription
hs_email_from_emailThe email address of the email's sender.
hs_email_from_firstnameThe email sender's first name.
hs_email_from_lastnameThe email sender's last name.
hs_email_to_emailThe email addresses of the email's recipients.
hs_email_to_firstnameThe first names of the email's recipients.
hs_email_to_lastnameThe last names of the email recipient.

Since headers automatically populate the read only properties, you may want to manually set the email headers. To set the hs_email_headers value, you can use a JSON escaped string with the following data:

For example, your request to create an email may look like:

To create and associate an email with existing records, include an associations object in your request. For example, to create an email and associate it with a deal and a contact, your request body might look like the following:

In the associations object, you should include the following:

FieldDescription
toThe record you want to associate with the email, specified by its unique id value.
typesThe type of the association between the email and the record. Include the associationCategoryand associationTypeId. Default association type IDs are listed here, or you can retrieve the value for custom association types (i.e. labels) via the associations API.

You can retrieve emails individually or in bulk. Learn more about batch retrieval by checking out the reference documentation.

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:

ParameterDescription
propertiesA comma separated list of the properties to be returned.
associationsA comma separated list of object types to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response. Learn more about the associations API.

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:

ParameterDescription
limitThe maximum number of results to display per page.
propertiesA comma separated list of the properties to be returned.

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:

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 checking out the reference documentation.

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}/{associationTypeId}. The request URL contains the following fields:

FieldDescription
emailIdThe ID of the email.
toObjectTypeThe type of object that you want to associate the email with (e.g., contact or company)
toObjectIdThe ID of the record that you want to associate the email with.
associationTypeIdA unique identifier to indicate the association type between the email and the other object. The ID can be represented numerically or in snake case (e.g., email_to_contact). You can retrieve the 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

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}/{associationTypeId}

You can pin an email on a record so it remains on the top of the record's timeline. The email must already be associated with the record prior to pinning, and you an only pin one activity per record. To pin an email, include the email's id in the hs_pinned_engagement_id field when creating or updating a record via the object APIs. Learn more about using the companies,contacts, deals, tickets, and custom objects APIs.

When you delete an email, it is permanently deleted and cannot be restored. You can delete emails individually or in batches.

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

Learn more about deleting emails by checking out the reference documentation.