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

Request payload

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

Top-level fields

• emailId
• message
• contactProperties
• customProperties

emailId

The emailId field is the content ID for the transactional email, which can be found in 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. 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

contactProperties

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.

customProperties

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

• 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.

SendResult

• 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: https://api.hubapi.com/email/public/v1/singleEmail/send