Transactional API Examples

This page contains some example requests to help get you started with our transactional API.

Send an email using a transactional message template

To send a message using a transactional message template, you need the following:

Using the data above, you can trigger a message with a request like the one below. This example is for a transactional message that includes two variables: first_name and passwordResetURL.

message='
{
  "to": "Sarah <sarah@example.io>",
  "transactional_message_id": 3,
  "message_data": {
    "first_name": "Sarah",
    "passwordResetURL": "https://www.example.io/password?token=12345"
  },
  "identifiers": {
    "id":"sf3sd"
  }
}
'

echo $message | curl -v https://api.customer.io/v1/send/email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d @-

Send an email without a transactional template

To send a simple request that doesn’t use a transactional template, you must provide all of your message information—to, from, subject, body, and one of identifiers.id, identifiers.email, or identifiers.cio_id—in the request.

message='
{
  "to": "Sarah <sarah@example.io>",
  "from":"win@customer.io",
  "subject":"Reset your password",
  "body":"Hello Sarah, you or someone in your team account has requested a password reset on your behalf.  Reset your password by clicking <a href='https://www.example.io/password?token=12345'>here</a>.</p>", 
  "identifiers": {
    "id":"d34sh"
  }
}
'

echo $message | curl -v https://api.customer.io/v1/send/email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d @-

 Messages sent without a transactional_message_id are ‘uncategorized’

Any messages you send without a transactional_message_id are grouped together in the All Uncategorized Messages bucket in your workspace. We strongly recommend creating transactional message templates, so that it’s easier to manage your messages and to separate reporting metrics for your different types of transactional messages.

Including an attachment

 Include PDF attachments from the asset library

While you can encode attachment and send them directly to people, you can also host PDFs in our asset library and link to them in your messages. This can save you the trouble of encoding and sending files directly.

You can include base64-encoded attachments in your request, like calendar invites, in the format: {"filename": "base64-encoded-file-body"}. Total attachments size, across all attachments for the message, must be under 2MB.

For example, here’s the text body of a simple calendar invite (example_invite.ics):

BEGIN:VCALENDAR
VERSION:2.0
PRODID:http://www.icalmaker.com
BEGIN:VEVENT
UID:http://www.icalmaker.com/event/69f018d0-a2b1-44c0-ac66-a28e8c493a6b
DTSTAMP:20201113T220919Z
DTSTART:20230504T113000Z
DTEND:20230504T123000Z
SUMMARY:Customer.io Calendar Example
LOCATION:921 SW Washington St., Suite 820, Portland, OR 97205
DESCRIPTION:Learn more about sending calendar invites as attachments at https://customer.io/transactional-api. 
END:VEVENT
END:VCALENDAR

You can base64-encode the invite and include it in your request like this.

message='
{
  "to": "Sandra <sandra@example.io>",
  "from":"win@customer.io",
  "subject":"Registration Confirmation",
  "body":"Attached is an invite to add to your calendar.", 
  "identifiers": {"id":"e5zs8"},
  "attachments":{"example_invite.ics": "QkVHSU46VkNBTEVOREFSClZFUlNJT046Mi4wClBST0RJRDpodHRwOi8vd3d3LmljYWxtYWtlci5jb20KQkVHSU46VkVWRU5UClVJRDpodHRwOi8vd3d3LmljYWxtYWtlci5jb20vZXZlbnQvNjlmMDE4ZDAtYTJiMS00NGMwLWFjNjYtYTI4ZThjNDkzYTZiCkRUU1RBTVA6MjAyMDExMTNUMjIwOTE5WgpEVFNUQVJUOjIwMjMwNTA0VDExMzAwMFoKRFRFTkQ6MjAyMzA1MDRUMTIzMDAwWgpTVU1NQVJZOkN1c3RvbWVyLmlvIENhbGVuZGFyIEV4YW1wbGUKTE9DQVRJT046OTIxIFNXIFdhc2hpbmd0b24gU3QuLCBTdWl0ZSA4MjAsIFBvcnRsYW5kLCBPUiA5NzIwNQpERVNDUklQVElPTjpMZWFybiBtb3JlIGFib3V0IHNlbmRpbmcgY2FsZW5kYXIgaW52aXRlcyBhcyBhdHRhY2htZW50cyBhdCBodHRwczovL2N1c3RvbWVyLmlvL3RyYW5zYWN0aW9uYWwtYXBpLiAKRU5EOlZFVkVOVApFTkQ6VkNBTEVOREFS"}
}
'
echo $message | curl -v https://api.customer.io/v1/send/email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d @-

The request results in a delivery with a calendar invite, which looks like this in Gmail:

image.png
image.png

Need help?

If you have another use case in mind, or need help applying one of these examples, let us know!

Copied to clipboard!
Is this page helpful?