Transactional Email

Access and test APIs in beta. 

Please note: This API is currently under development and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer Developer Beta Terms of Use. You also acknowledge and understand the risk associated with testing an unstable API. 
 

This API is currently in beta. For the latest stable version check out this page.

Requirements

To use Transactional Email features, you must purchase the transactional email add-on, which includes use of a unique, dedicated IP address. (Learn how to set up a dedicated IP here.)

Using transactional email:

Depending on how you want to create and trigger your transactional email sends, there are three ways to implement this functionality:

Here's a brief overview of each method:

 

  in-app transactional Email
SMTP API
Single-send API
At a glance transactional-overview.png
Overview Create beautiful transactional emails using HubSpot's email editor. You'll get all the benefits of smart content, personalization and templates — just like regular HubSpot emails.

Just choose ‘Transactional’ as your email type and we will automagically remove subscription preferences for you, since this is a non-marketing email to your customers/users.

You can then send or schedule your email. Or ‘Save for automation’ to send with an automated workflow. Simple!
Sending transactional email through your own site or app? No problem.

The SMTP API integration allows you to continue to do just that - along with tracking email performance and creating contact information (optional) within HubSpot, without having to rip out any existing systems. The optional ability to create contact information is decided upon the smtp token creation.


Generate an SMTP token from your HubSpot email dashboard, send us a fully formed email triggered via API and we’ll add open and duration tracking, as well as wrap all your links for click info.

For more info - check out the SMPT API section
The best of both worlds!

Create beautiful transactional emails right within HubSpot using the email editor with all the benefits of smart content, personalization and templates - just like regular HubSpot emails.

PLUS add custom tokens (that live outside of HubSpot) to your email which you can send us via your API.

Instead of saving for automation in HubSpot - choose ‘Save for single-send API’. The email will send when triggered from your system and performance data will automatically be tracked in HubSpot. Nice!

For more info - check out the Single-send API section
Example use case You want to send a 'Policy Update' email to your customers with a link to a new T&C's page. This is a service update, not a marketing email so you don't legally need to include subscription links (e.g CAN SPAM links). You don't need to use any custom properties or info from external systems. You are sending an 'Account Signup Confirmation' email from a separate transactional email system that you are not ready to move away from yet. But want to be able track email performance and create contact information (optional) in HubSpot. You want to send a 'Purchase Receipt' email to your customer using HubSpot. But you need to trigger the email send (e.g. when purchase is complete) and pass custom values (e.g. purchased item and purchase total values) from another system. You also want to track the performance of this email in HubSpot.

 


SMTP API

*Please note: The use of this API requires the transactional email add-on.

The SMTP API doesn't send emails directly, but is used to get login credentials for the HubSpot SMTP server. After you get a token and password using the API, you'll need to use those credentials to log into HubSpot's SMTP server and send the email over SMTP. The login details (hostname and port) for the SMTP server can be found below in the generate SMTP API token section

Transactional email sent using the SMTP API is automatically triggered by specific criteria, like making a purchase on an ecommerce website. The SMTP API integrates with any internal or third-party systems to both trigger the email and incorporate data stored outside of HubSpot (e.g. shipping info, purchase price, etc). The email is sent from your system, but is wrapped with HubSpot tracking codes that allow full engagement tracking and measurement.

Using the SMTP API

In order to send emails using the SMTP API, you will need to make use of SMTP API tokens. The five methods outlined in this documentation all deal with these tokens and have counterparts in the Transactional Email UI, which can be used to obtain the same information. Here we will take a look at which parts of the UI correspond to these methods.

Note: All the methods in the SMTP API require an OAuth token for authentication. Please refer to this guide for details to generate and use these tokens.

 

1. List SMTP API tokens

  • GET a list of tokens using the endpoint /marketing/v3/transactional/smtp-tokens described in the endpoints tab or
  • Go to Settings > Marketing > Email, then select the SMTP tab. 
Request query parameters

The following optional parameters are supported:

  • campaignName - A name for the campaign tied to the SMTP API token.
  • emailCampaignId - Identifier assigned to the campaign provided in the token creation request.
  • after - Starting point to get the next set of results. See paging field in the response below.
  • limit - Maximum number of tokens to return.

Response details

The response contains results and paging as its top-level fields.

results

A collection of SmtpApiTokenView.

SmtpApiTokenView object fields:

  • id - Username to log into the HubSpot SMTP server.
  • createdBy - Email address of the user that sent the token creation request.
  • emailCampaignId - Identifier assigned to the campaign provided in the token creation request.
  • createdAt - Timestamp generated when a token is created.
  • createContact - Indicates whether a contact should be created for email recipients.
  • campaignName - A name for the campaign tied to the token.

paging

Contains a next.after field that can be used to request more results.

 

2. Get details for a single SMTP API token

  • GET details for a single token using the endpoint /marketing/v3/transactional/smtp-tokens/{tokenId} described in the endpoints tab, or 
  • Go to Settings > Marketing > Email. Go to the SMTP tab, click the "Actions" button for the token you'd like to view, and select “View details.”
Request parameter

The ID of a SMTP API token, which is provided when a token is generated.


Response details

The response includes a single SmtpApiTokenView as described in the “List SMTP API Tokens” section.

 

Screen Shot 2020-04-15 at 12.42.33 PM
Screen Shot 2020-04-15 at 12.42.50 PM

3. Generate SMTP API tokens 

An API token provides a username and password that can be used to send email through the HubSpot SMTP API:

  • SMTP Hostname: smtp.hubapi.com
  • SMTP Port: 587 (for STARTTLS) or 465 (for TLS)
  • SMTP User Name: provided in the ID field
  • SMTP Password: provided in the password field

Note: SMTP API tokens generated through the public API expire after 12 months. Once expired, they're automatically deleted.

 

  • Generate tokens through a POST request to the endpoint /marketing/v3/transactional/smtp-tokens/ described in the endpoints tab, or
  • Generate tokens through the Transactional Email UI within the email tool: Go to Settings > Marketing > Email, then select the SMTP tab. Click the "Generate token" button and enter a name for the token. Make sure you record the token password, as you can't retrieve it later, only reset it.

 

Request payload

The request body must be a JSON-formatted object with the properties listed below.

  • createContact - Indicates whether a contact should be created for email recipients.
  • campaignName - A name for the campaign tied to the SMTP API token.

 

Response details

The response includes a SmtpApiTokenView. SmtpApiTokenView object fields:

  • id - Username to log into the HubSpot SMTP server.
  • createdBy - Email address of the user that sent the token creation request.
  • password - Password used to log into the HubSpot SMTP server.
  • emailCampaignId - Identifier assigned to the campaign provided in the token creation request.
  • createdAt - Timestamp generated when a token is created.
  • createContact - Indicates whether a contact should be created for email recipients.
  • campaignName - A name for the campaign tied to the token.

list_tokens

 

name_token

 

token_name_pass

Note: The “Token Name” and “UserName” columns displayed in the UI correspond to the campaignName and id fields, respectively, in the SmtpApiTokenView object of the public API.

 

4. Reset password

  • Reset through a POST request using the endpoint /marketing/v3/transactional/smtp-tokens/{tokenId}/password-reset , or
  • Click on the "Actions" button for the token you'd like to reset the password for and select "Reset Password."
Request parameter

The ID of a SMTP API token, which is provided when a token is generated.

Response details

The response includes a single SmtpApiTokenView, as described in the “List SMTP API Tokens” section.

token_actions_menu

5. Delete a SMTP API token

  • DELETE a single token using the endpoint /marketing/v3/transactional/smtp-tokens/{tokenId} described in the endpoints tab, or 
  • Go to Settings > Marketing > Email. Go to the SMTP tab, then click on the "Actions" button for the token you'd like to remove, and select “Delete.”
Request parameter

The ID of a SMTP API token.

Response details

No content is returned.


Single-send API

*Please note: The use of this API requires the transactional email add-on.

The Single-send API sends template emails created in the HubSpot email tool using a JSON-formatted POST call.

Using the Single-send API

When creating an email in HubSpot, select "Save for single-send API" in the "Select recipients" section. After the email is created, you can set the recipient details (including any contact or custom properties set up in the email) in the body of the API request.

Any emails sent through this API will be automatically associated with contact records based on email address. If there's no contact with a matching email address, a new contact with that email will be created. If you want to send emails without creating contacts, use the SMTP API.

Note: The HTML/JSON sent through this API isn't saved by HubSpot. You may review the template of the email from the contact's timeline event. If you wish to keep a record of the emails sent and their contents, we recommend adding a BCC to the email.

Once the email is published, you'll see the email ID at the bottom of the page:

 

Screen Shot 2020-04-15 at 1.00.37 PM

Request payload

The request body must be a JSON-formatted object with the properties listed below.

Top-level fields

  • emailId
  • message
  • contactProperties
  • customProperties
emailId

The emailId field contains the transactional email's content ID, which can be found in the email tool UI.

message

The message field is a JSON object containing anything that you want to override. At the minimum, the to field must be present.

Message object fields:

  • to — The recipient of the email
  • from — The "From" header for the email. You can define a from name with the following format: "from":"Sender Name <sender@hubspot.com>"
  • sendId — The ID of a particular send. Only one email with a given sendId will be sent per account, so including this field is a good way to prevent duplicate email sends.
  • replyTo — A JSON list of "Reply-To" header values for the email.
  • cc — A JSON list of email addresses to send as Cc.
  • bcc — A JSON list of email addresses to send as Bcc.
contactProperties

The contactProperties field is a JSON map of contact property values. Each contact property value contains a name and value. Each property will be set on the contact record and will be visible in the template under . Use these properties when you want to set a contact property while you’re sending the email. For example, when sending a receipt you may want to set a last_paid_date property, as the sending of the receipt will have information about the last payment.

Example:

{

  “property_name_1”: “property_value_1”,

  “property_name_2”: “property_value_2”

}

customProperties

The customProperties field is a JSON map of property values. Each property value contains a name and value property. Each property will be visible in the template under {{custom.NAME}}.

Note: Custom properties do not currently support arrays. To provide a listing in an email, one workaround is to build an HTML list (either with tables or ul) and specify it as a custom property.

Example:

{

  “property_name_1”: “property_value_1”,

  “property_name_2”: “property_value_2”

}

 

Response details

The response contains the following fields:

    • requestedAt — The timestamp of when the send was requested.
  • statusId — An identifier that can be used to query the status of the send.
  • status — The status of the send request. One of [PENDING, PROCESSING, CANCELLED, COMPLETED]

 

Example URL to POST to: https://api.hubapi.com/marketing/v3/transactional/single-email/send


Query the status of an email send

Request details

Make a GET request to https://api.hubapi.com/marketing/v3/email/send-statuses/{statusId} with the statusId of the send.

Response details

The response contains the following fields:

    • sendResult — A SendResult value (see below)
    • requestedAt—The timestamp from when the send was requested.
  • startedAt — The timestamp when the send began processing.
  • completedAt — The timestamp when the send completed.
  • statusId — An identifier that can be used to query the status of the send.
  • status — The status of the send request. One of [PENDING, PROCESSING, CANCELLED, COMPLETED]
  • eventId — If sent, the ID and created timestamp of the sent event.

SendResult

The SendResult is an enumeration of possible results when attempting to send the email.

  • SENT — The email was sent successfully.
  • QUEUED — The email was queued, and will send as the queue gets processed.
  • PORTAL_SUSPENDED — Due to Acceptable Use Policy violations, the HubSpot customer's email has been suspended.
  • INVALID_TO_ADDRESS — The recipient address is invalid.
  • BLOCKED_DOMAIN — The domain cannot receive emails from HubSpot at this time.
  • PREVIOUSLY_BOUNCED — The recipient has previously bounced, and the sending logic resulted in no send.
  • PREVIOUS_SPAM — The recipient has previously marked similar email as spam.
  • INVALID_FROM_ADDRESS — The From address is invalid.
  • MISSING_CONTENT — The emailId is invalid, or the emailId corresponds to an email that wasn't set up for Single Send.
  • MISSING_TEMPLATE_PROPERTIES — There are custom properties set up in the template that have not been included in the customProperties sent in the request.