There's a new version of the HubSpot API

Starting November 30, 2022, API keys will be sunset as an authentication method. Learn more about this change and how to migrate an API key integration to use a private app instead.

Send a single transactional email

Last updated March 1, 2021

POST /email/public/v1/singleEmail/send

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?






Required Scope:


Please note: The use of this API requires the Transactional Email add-on.

This method is used to send an email designed and maintained in the Marketing Hub's email tool.

By selecting "Save for single send API" during the recipient step of building an email, you can use this API to render the email, add some customizations on the fly, and send the email to the intended recipient. The Email ID provided in the email tool specifies which template to render.

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

Note: The HTML/JSON that is sent through this API is not saved by HubSpot. You may review the template of the email from the contact's timeline event, but you cannot view the original email as sent to the contact. If you wish to keep a record of the email sent and its contents, we recommend adding a BCC to the email.

Use case for this API: This capability would be useful in a situation where an event on an external system should trigger an email send, for example.

Selecting recipients

If you have the Transactional Email add-on, the email tool allows you to select "Save for single send API." This option will enable the email for use with this API.

API parameters

Required parameters How to use Description
OAuth Access Token or API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.
Used to authenticate the request. Please see this page for more details about authentication.
Email ID Used in the request body JSON (see below) The ID of the email to send, from the email tool when viewing a transactional email.
Message Used in the request body JSON (see below) A JSON object holding the recipient (in its to field) as well as other customizations that can be made on the fly. (See below.)
Optional parameters How to use Description
Contact properties Used in the request body JSON (see below) A list of JSON objects representing contact property values to set when sending the email. Useful if you have more information about the contact when sending the email.

You can get the full list of available contact properties and their names using the Contact Properties API.
Custom properties Used in the request body JSON (see examples below) A list of JSON objects representing property values to set when sending the email. Useful if you have context in the email you don't want to set on the contact record.
Other message options Used in the request body JSON Other data about the email you want to send.

Request payload

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

Top-level fields

  • emailId
  • message
  • contactProperties
  • customProperties


The emailId field is the content ID for the transactional email, which can be found in email tool UI.


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 <>"
  • sendId — The ID of a particular send. No more than one email with a given sendId will be send per portal, so including a sendId is a good way to prevent duplicate email sends.
  • replyTo — The Reply-To header for the email
  • replyToList — 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


The contactProperties field is a JSON array of contact property values. Each contact property value contains a name and value property. Each property will get set on the contact record and will be visible in the template under {{ contact.NAME }}. 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.


The customProperties field is a JSON array 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.

Note: Custom properties are not stored in HubSpot, and will only be included in the email sent to the contact. These properties will not appear in the web page version of the email, or in the view of the email from the contact's timeline.

Response details

The response contains the following fields:
  • sendResult — A SendResult value (see below)
  • message — A description of the send result details.
  • eventId — If sent, the id and created timestamp of the sent event.


The SendResult is an enumeration of possible results when attempting to send the email. In practice, if the status code of the response is in the 400 range you should not attempt to resend. If the response is in the 500 range then the request failed.
  • 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 is an email that is not 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.

Example URL to POST to: