Send a transactional email

Server

US region

Client Libraries

Shell Curl

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.

Body

application/json

to
Type: string
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.
attachments
Type: object

A dictionary of attachments where the filename is the key and the value is the base64-encoded contents. The filename must include the extension (i.e. name.csv). The total size of all attachments must be less than 2 MB.
auto_create
Type: boolean

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.
bcc
Type: string

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.
body
Type: string

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_amp
Type: string

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_plain
Type: string

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

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.
disable_css_preprocessing
Type: boolean

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.
disable_message_retention
Type: boolean

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.
fake_bcc
Type: boolean

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).
from
Type: string

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.
headers
Type: string Format: 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.
identifiers

Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
Identifies the person represented by your transactional message by one of, and only one of, id, email, or cio_id.
id
Type: string
required

The identifier for the person represented by the transactional message. NOTE: If your workspace identifies people by email, use the email identifier instead.
language
Type: string

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.
message_data
Type: object

An object containing the key-value pairs referenced using liquid in your message.
preheader
Type: string

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.
queue_draft
Type: boolean

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.
reply_to
Type: string

The address that recipients can reply to, if different from the from address.
send_at
Type: integer

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.
send_to_unsubscribed
Type: boolean

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.
subject
Type: string

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

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

The transactional message template you want to use. You can call the template by its numerical ID or by the Trigger Name that you assigned to the template in the UI (case insensitive).
Type: integer · ID (integer)

The ID of the transactional message you want to send.

Responses

application/json
application/json
application/json
application/json

post/v1/send/email

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

Show Schema

{
  "delivery_id": "string",
  "queued_at": 1,
  "send_at": 1
}

Returns a unique ID for the delivery.

Send a transactional email

Authentication

Send a transactional email