Transactional API Examples

Updated

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

Send a push notification using a transactional message template

To send a transactional push notification, 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 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 @-

Send a transactional in-app message

To send a transactional in-app message, you need:

  • transactional_message_id: the numeric ID or trigger name for an in-app template you’ve created in the UI.
  • identifiers: a unique identifier for the recipient. The Customer.io SDK uses this to route the message to the right person’s devices.
  • message_data (optional): values you want to populate in the template using {{trigger.<property_name>}}.

In-app messages don’t accept body or subject overrides; the content comes from the template you reference.

message='
{
  "transactional_message_id": "order_confirmation",
  "identifiers": {
    "id": "user_123"
  },
  "message_data": {
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678"
  }
}
'

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

Auto-create a transactional record from the API

For email and push notifications, you can pass the auto_create parameter to create a record for you when you first send a message. This provides a way to create and manage transactional messages so you can still track metrics for messages from code or agentic workflows.

See more details for email and push notifications.

message='
{
  "transactional_message_id": "order_confirmation",
  "auto_create": true,
  "to": "sarah@example.io",
  "identifiers": {
    "id": "sf3sd"
  },
  "from": "win@customer.io",
  "subject": "Your order is confirmed",
  "body": "Thanks for your order, {{customer.first_name | default: \"there\"}}!"
}
'

echo $message | curl -v https://api.customer.io/v1/send/email \
-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!

Copied to clipboard!
  Contents