Transactional API - Examples

Below are a few example Transactional API requests to help get you started.

Send an email using a transactional message template (for id-based workspaces)

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.
    image.png
    image.png
  • message_data - A list of variables used in your template (if any).
  • App API Key - Find or create your App API key from your Account Settings.
  • Recipient email - The email address for the to field, and
  • identifiers.id - The unique id for the recipient in your workspace, so that the delivery can be associated with the correct profile.

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 using a transactional message template (for email-based workspaces)

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.
    image.png
    image.png
  • message_data - A list of variables used in your template (if any).
  • App API Key - Find or create your App API key from your Account Settings.
  • Recipient email - The email address for the to field, and
  • identifiers.email - The unique email for the recipient in your workspace, so that the delivery can be associated with the correct profile.

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": {
    "email":"sarah@example.io"
  }
}
'

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

Sending 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 identifiers.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 @-

 Uncategorized Messages

Messages sent without a transactional_message_id are grouped together in the All Uncategorized Messages bucket in your workspace and reported in-aggregate. 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

You can include base64-encoded attachments, 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 so:

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!