20

Transactional messages

Transactional messages are email or push notifications that your audience implicitly opts-into, like a transaction receipt or a password reset request. You can send transactional messages programmatically through Customer.io

How it works

A transactional message is a message your audience implicitly opts into, regardless of whether they’ve opted out of marketing messages or not—like purchase receipts, password reset requests, shipping updates, etc.

The Transactional API makes it easy to trigger transactional messages based on things your audience do in your app or website. You can either create a transactional template in Customer.io—a message that you’ll populate with data from an API call, or you can send your entire message body through the API.

In general, we recommend that you use the template option, because it’s easier to design a message in Customer.io, reduces the size of the payload you need to store on your end, and it makes it easy to track engagement with your transactional messages. We aggregate metrics for all messages that don’t call a specific transactional_message_id—the template you create in Customer.io—as “uncategorized messages”; so, if you send three different message bodies through our API without a transactional_message_id template, we’ll count the metrics for all three messages together.

Use cases

Our transactional APIs help you separate transactional and marketing messages, while still being able to see and manage both types of messages in the same platform. We don’t charge extra for this service! Common use cases for transactional messages include:

• Purchase receipts
• Registration confirmations
• Password resets
• Trial expiration reminders
• Comment notifications
• Event reminders
• Shipping updates
• Support and feedback requests

Identifying your recipients

When you trigger a transactional message, you’ll specify an identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for a person—one of id, email, or cio_id (depending on the identifiers allowed by your workspace). If a person matching the id or email in your request doesn’t exist, we’ll create a new person.

Transactional Emails

Before you begin

Before you can send transactional emails you need to:

• Confirm your registration email and verify your account.
• Authenticate your sending domain. If you configured a custom SMTP server, contact us to manually authenticate your sending domain.
• Get your App API key. This is the bearer token that you’ll use when calling the transactional API. App API keys are not the same as the Tracking API keys that you use to update profiles and trigger events. CIO does not store App API keys (only a hashed version) and you can restrict App API keys to specific IP addresses for extra security.

We also recommend that you use a different, specialized domain or subdomain for transactional messages. A sending domain is the domain of the “From email address” when you send emails, and you can request that we add your transactional domain to our specialized, transactional IP pool. Email providers like Gmail monitor the sending domain for unusual behavior and spam complaints. Separating your transactional domain from your marketing domain—something like marketing.example.com and transactional.example.com—prevents your marketing messages from affecting your critical transactional messages. Learn more about domain reputation.

Create a transactional email

1. Go to the Transactional page and click Send your first message or Create message—depending on whether there are already transactional messages in your workspace.

2. Name your message and provide a description. These fields help your team members understand what kind of message this is (like “Password Reset Instructions”). You can also use the Name of your message instead of the transactional_message_id when you send your message.

   

   

3. Click Add Content to create and manage your message template in Customer.io. This generates the transactional_message_id that you’ll refer to when you send your message.

   

   

4. Add your content. Choose your editor, or start from an existing email. When you build your email, you can personalize messages using attributes (customer.<attribute>) or API trigger data (trigger.<data-object-property>) to customize your message.

5. Configure your message settings.

   • Send to unsubscribed people? Unsubscribed people probably still want to receive your important transactional messages.

     The FTC provides guidelines about what qualifies as a transactional message, including what to do for messages that combine transactional and marketing content.

   • Enable open and link tracking? Enable this setting if you need to know if people open or click links in your transactional messages.

   • Protect sensitive data by disabling message retention? This setting prevents Customer.io from retaining your message content in delivery history and associated API calls. You might want to do this to conceal sensitive content, like password reset tokens.

   • Queue messages as drafts? This setting generates a draft for every message you trigger, rather than sending them automatically. You can review these messages under the “Drafts” tab and decide whether to send or delete them.

   • Set a Trigger Name: This is a friendly name for your message that you can use instead of the transactional_message_id when you send your message. It may help make your integration more human-readable if you use triggers that represent the kinds of messages you send—like password reset or order confirmation.

   

   

6. To complete the setup, you need to call the API and trigger a message. If you’re not yet ready to send a message directly from your code, you can use an HTTP client like Postman or send a cURL request from your terminal to test your message and complete the setup process.

   

   

Parameters supported by the transactional email API

This is a list of parameters for transactional message payloads. Your payload changes based on whether you reference a transactional_message_id (a template) or not. See our REST API documentation for more information.

Update the content of your email

You can update the contents of your message through our user interface. Changes to your message take effect immediately: any messages you trigger after your update will use the new content.

We’ve also exposed an API endpoint, so you can manage your message contents programmatically. This request takes a body, which represents the complete HTML content of your message.

You’ll reference the message you want to update by transactional_id and content_id. You can find both in the URL when you look at the content of a message in the format https://fly.customer.io/journeys/env/last/composer/transactional/:transactional_message_id/templates/:content_id. For example, if I look at a transactional message with this URL: https://fly.customer.io/journeys/env/last/composer/transactional/3/templates/139, then the transactional_id is 3 and where the content_id is 139.

curl --request PUT \
  --url https://api.customer.io/v1/transactional/{transactional_id}/content/{content_id} \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"body":"string"}'

Transactional push notifications

Before you begin

Before you can send transactional push notifications you need to:

• Enable Push Notifications in your workspace for Android and/or iOS.
• Set up your app to receive push notifications from Customer.io. We strongly recommend that you use our SDKs. If this isn’t an option, you can follow the instructions here to configure push without our SDKs.

Create a transactional push notification

1. Go to the Transactional page and click Send your first message or Create message—depending on whether there are already transactional messages in your workspace.

2. Name your message and provide a description. These fields help your team members understand what kind of message this is (like “Password Reset Instructions”). You can also use the Name of your message instead of the transactional_message_id when you send your message.

   

   

3. Click Next: Add Content to go to the next step. Select Push to create a transactional push notification.

   

   

4. Click Add Content and compose your push notification. Add images, deeplinks and custom data through the editor, or provide these values in the API request. You can also use attributes (customer.<attribute>) or API trigger data (trigger.<data-object-property>) to customize your message.

    Need to track personalized links?

   Add the data-cio-tag attribute to your links. This lets you track different individualized links in the same category, so you can gather useful metrics about clicks to things like personalized product recommendations, password reset links, customer dashboards, etc. The data-cio-tag takes a string representing the “group” you want to track—<a href="http://mydomain.com?token=123abc" data-cio-tag="YOUR-LINK-GROUP-NAME">CLICK HERE</a>

5. Configure your message settings.

   • Send to unsubscribed people? Unsubscribed people usually still want to receive your important transactional messages.

   • Protect sensitive data by disabling message retention? This setting prevents Customer.io from retaining your message content in delivery history and associated API calls. You might want to do this to conceal sensitive content, like password reset tokens.

   • Queue messages as drafts? This setting generates a draft for every message you trigger, rather than sending them automatically. You can review these messages under the “Drafts” tab and decide whether to send or delete them.

   • Set a Trigger Name: This is a friendly name for your message that you can use instead of the transactional_message_id when you send your message. It may help make your integration more human-readable if you use triggers that represent the kinds of messages you send—like password reset or order confirmation.

   

   

6. To complete the setup, you need to call the API and trigger a message. If you’re not yet ready to send a message directly from your code, you can use an HTTP client like Postman or send a cURL request from your terminal to test your message and complete the setup process.

Parameters supported by the transactional push API

This is a list of parameters for transactional message payloads. Your payload changes based on whether you reference a transactional_message_id (a template) or not. See our REST API documentation for more information.

Localize a transactional message

When you add content to your message, you can click Add language to select the languages you want to support. Then you can populate your languages, and we’ll automatically send your audience the language matching their language attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages..

To take advantage of our localization feature, you must have set up an attribute to capture your audience’s language preference. See our localization section for more information about setting up multi-language messages.

When you send your message, we’ll match your audience’s language attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages.—their preferred language—with the languages in your transactional message. If a person’s language attribute matches a language in your transactional message, we’ll send them the appropriate language. If their language attribute does not match a language in your template, they’ll receive the default message.

Override your audience’s language

If you don’t manage your audience’s language preferences in Customer.io, or you need to override your audience’s language preference for any reason, you can set a language property in your transactional message request. This value represents the language variant that you want to send to the recipient.

If the language doesn’t match one of your message’s languages, we’ll use the recipient’s language attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages.. If the language doesn’t match one of your message’s languages, and your audience doesn’t have a language attribute that matches one of your message’s languages, we’ll send the default message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{

  "transactional_message_id": 44,
  "to": "cool.person@example.com",
  "from": "override-templated-address@example.com",
  "subject": "Did you really login from a new location?",
  "language": "es",
  "identifiers": {
    "id": 12345
  },
  "message_data": {
    "password_reset_token": "abcde-12345-fghij-d888",
    "account_id": "123dj"
  },
  "bcc": "bcc@example.com",
  "disable_message_retention": false,
  "send_to_unsubscribed": true,
  "tracked": true,
  "queue_draft": false,
  "disable_css_preprocessing": true
}

Copy transactional messages to another workspace

You can copy a transactional email to another workspace to save yourself time creating similar messages.

Go to Transactional in the left hand navigation to get started. Filter or scroll to find the transactional message you want to copy. Then select the three dots to the right of the message and click Copy to.

On the modal, select the workspace you want to copy your items to then click Continue.

Note that when you copy transactional messages, we’ll reset settings that don’t exist in the destination workspace—like layout, audience, etc. You should also check your 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}}. syntax in your destination workspace. You may not have the same attributes or other variables in your destination, so you may need to update liquid statements to make sure that your messages render and send properly.