Sign in
Send Messages

Send a transactional email

Send a transactional email. While not strictly required, we recommend that you include a transactional_message_id in your request. If you don't, Customer.io attributes metrics to "transactional_message_id": 1, so multiple messages can roll up under the same ID.

If this is the first time you send a message with the API, you can include the auto_create parameter along with a transactional_message_id string to create a record for you.

You can also include a body, subject, and from values to override the message template. Or, if you create your message entirely through the API, you must include these values because your transactional_message_id won't have any content. See Examples and API parameters for more details.

post/v1/send/email

Headers

X-Workspace-Idinteger
Example:100

The numeric ID of the workspace you want to send a message in. This header is only needed when you authenticate with a service-account bearer token (sa_live_…). Service accounts work across workspaces, so you must supply this header so we know which workspace to send from. You can omit this header when you authenticate with a standard App API key, which is always scoped to one workspace.

Request body

bodystring

The HTML body of your message. If you provide a transactional_message_id, this overrides the template's body. It's also the fallback when you send AMP email (body_amp) to a client that doesn't support AMP.

body_ampstring

AMP-enabled content for your email. If a recipient's email client doesn't support AMP, they receive your body content instead. Make sure you're set up to send AMP first.

body_plainstring

The plaintext body of your message. If you provide transactional_message_id, this overrides the template's plaintext body.

subjectstring

The subject line for your message. If you provide transactional_message_id, this overrides the template's subject.

fromstring

The address your email is from. It must be a verified sender. Quote any display name, like \"Person\" <person@example.com>. This overrides the template's sender; omit it to use the template or your workspace default.

languagestring

Overrides language preferences for the person you want to send your transactional message to. Use one of our supported two- or four-letter language codes.

auto_createboolean

If true and your transactional_message_id doesn't match a record, Customer.io creates an empty record using that value as the Trigger Name. The ID must be a string. If the name already belongs to another channel, the request fails with 400, and numeric IDs ignore this setting. See details.

message_dataobject

An object containing the key-value pairs referenced using liquid in your message.

send_atinteger

A unix timestamp (seconds since epoch) determining when the message will be sent. The timestamp can be up to 90 days in the future. If this value is in the past, your message is sent immediately.

disable_message_retentionboolean

If true, the message body is not retained in delivery history. Setting this value overrides the value set in the settings of your transactional_message_id.

send_to_unsubscribedboolean

If false, your message is not sent to unsubscribed recipients. Setting this value overrides the value set in the settings of your transactional_message_id.

queue_draftboolean

If true, your transactional message is held as a draft in Customer.io and not sent directly to your audience. You must go to the Deliveries and Drafts page to send your message.

tostring required

The recipients you want to send to, separated by commas. You can include up to 15 total recipients across to, cc, and bcc, with optional display names in quotes.

ccstring

Carbon copy message recipients, separated by commas. Unlike BCC recipients, CC recipients are visible to everyone who receives the message. Their opens, clicks, and bounces count toward your message metrics. CC recipients count toward the limit of 15 total recipients across the to, cc, and bcc keys.

bccstring

Blind copy message recipients. Supports multiple addresses separated by commas. Your request can contain up to 15 total recipients between the to, cc, and bcc keys.

fake_bccboolean

If true, rather than sending true copies to BCC addresses, Customer.io sends a copy of the message with the subject line containing the recipient address(es).

reply_tostring

The address that recipients can reply to, if different from the from address.

preheaderstring

Also known as "preview text", this is the block block of text that users see next to, or underneath, the subject line in their inbox.

headersstring json

A JSON string containing header objects with name and value. Names and values must be strings, with no non-ASCII characters or spaces. You can't overwrite reserved headers.

disable_css_preprocessingboolean

Set to true to disable CSS preprocessing. This setting overrides the CSS preprocessing setting on the transactional_message_id as set in the user interface. Transactional emails have CSS preprocessing enabled by default.

trackedboolean

If true, Customer.io tracks opens and link clicks in your message.

Example request

{
  "transactional_message_id": 44,
  "to": "cool.person@example.com",
  "from": "override-templated-address@example.com",
  "subject": "Order receipt",
  "identifiers": {
    "email": "cool.person@example.com"
  },
  "message_data": {
    "password_reset_token": "abcde-12345-fghij-d888",
    "account_id": "123dj"
  },
  "attachments": {
    "file1.csv": "base64encodedcontent",
    "file2.pdf": "base64encodedcontent"
  },
  "headers": {
    "X-Mailgun-Tag": "my-cool-tag"
  },
  "bcc": "bcc@example.com",
  "disable_message_retention": false,
  "send_to_unsubscribed": true,
  "tracked": true,
  "queue_draft": false,
  "disable_css_preprocessing": true
}

Response

Returns a unique ID for the delivery.

delivery_idstring

A unique identifier for the message.

queued_atinteger

A Unix timestamp for when Customer.io accepted and queued your request. For scheduled messages (using send_at), this is when we received your request, not when the message sends.

send_atinteger

For a scheduled message, the Unix timestamp when the message is set to send. Returned only when you provide a future send_at.

Changes

No recorded changes to this endpoint across all 1 revision of this API.