Single Send API

POST /email/public/v1/singleEmail/send

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Send an email designed and maintained in the HubSpot marketing Email Tool.

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

By selecting "Save for single send API" during the recipient step of building an email, you can use this endpoint 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 is used to specify 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.

Selecting Recipients

If you have the Transactional Email Add-on, the Email Tool will allow 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 property values to set when sending the email. Useful if you have more information about the contact when sending the email.
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

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

Response Payload

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.

SendResult

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.

Example URL to POST to:  https://api.hubapi.com/email/public/v1/singleEmail/send?hapikey=demo