There's a new version of the HubSpot API

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Send a single transactional email

Last updated May 12, 2023

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 in the marketing email tool.

After you design and publish a transactional email in your HubSpot account, you can use this API to include customization options to the email, then send it to the intended recipient. The Email ID provided in the marketing email tool specifies which template to include in your API request.

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.

Publish a transactional email in your HubSpot account

First, design your transactional email in your HubSpot account using the email editor tool:

  • In your HubSpot account, navigate to Marketing > Email.
  • In the top right, click Create email.
  • In the dialog box, select Regular for the email type.
  • Select a template.
  • Edit your email. You can use personalization tokens in transactional emails, just as you would with your marketing emails.
  • When you're done editing your email, click the Actions dropdown menu in the top right, then select Convert to single-send API.

  • Finish configuring your email, then click Review and save in the top right.
  • In the right panel, click Save for single-send API.
  • Once the email has saved, you can copy the email ID to use in your API request.


Review the other parameters available in the table below.

API parameters

Required parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header 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. This error will also occur if you attempt to send an email with any of the following role-based prefixes in the email address: abuse, no-reply, noreply, root, spam, security, undisclosed-recipients, unsubscribe, inoc, postmaster, or privacy.
  • 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: