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: stringFormat: 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

curl https://api.customer.io/v1/send/email \
  --request POST \
  --header 'X-Workspace-Id: 100' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "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
}'

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