30

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:

• transactional_message_id: This is found in the code examples when setting up a transactional message. It’s also the id listed in the URL of a transactional message.

  

  
• message_data: A list of data that you want to pass into your message using liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}..
• Your API Key: This is how you’ll authenticate with Customer.io’s API. You can find or create your App API key from your Account Settings.
• Recipient email - The email address for the to field, and
• identifiers.id, identifiers.email, or identifiers.cio_id: a unique identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for the recipient, so your message is associated with the correct person.

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 @-

Including an attachment

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:

Send a push notification using a transactional message template

To send a transactional push notification, you need the following:

• transactional_message_id: This is found in the code examples when setting up a transactional message. It’s also the id listed in the URL of a transactional message.

  

  
• message_data: A list of data that you want to pass into your message using liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}..
• Your API Key: This is how you’ll authenticate with Customer.io’s API. You can find or create your App API key from your Account Settings.
• identifiers.id, identifiers.email, or identifiers.cio_id: a unique identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for the recipient, so your message is associated with the correct person.

Using the data above, you can trigger a message with a request like the one below. This example is for a transactional message that sends a push notification to the recipient’s last used device and includes two variables: first_name and passwordResetToken.

message='
{
  "to": "last_used",
  "transactional_message_id": 3,
  "message_data": {
    "first_name": "Sarah",
    "passwordResetToken": "token=12345"
  },
  "identifiers": {
    "id":"sf3sd"
  }
}
'

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

Need help?

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