10

Set up a transactional email

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.

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 track API keys that you use to update profiles and trigger events. Customer.io 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 and set up your message. You’ll 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.

   

   

4. 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.

   

   

5. 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.

   

   

Examples and API parameters

Below are examples of transactional emails. We’ve provided a basic payload and examples for cURL, our Node.JS SDK, and our Python SDK.

We’ve also provided 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.

{
  "transactional_message_id": 44,
  "to": "cool.person@example.com",
  "subject": "Did you really login from a new location?",
  "identifiers": {
    "email": "cool.person@example.com"
  },
  "message_data": {
    "password_reset_token": "abcde-12345-fghij-d888",
    "account_id": "123dj"
  },
  "send_to_unsubscribed": true,
  "tracked": true,
  "disable_css_preprocessing": true
}

const { APIClient, SendPushRequest, RegionUS } = require("customerio-node");
const api = new APIClient('app-key', { region: RegionUS });

const request = new SendPushRequest({
  to: "person@example.com",
  transactional_message_id: "44",
  message_data: {
    password_reset_token: "abcde-12345-fghij-d888",
    account_id: "123dj"
  },
  identifiers: {
    id: "2",
  },
});

api.sendPush(request)
  .then(res => console.log(res))
  .catch(err => console.log(err.statusCode, err.message))

from customerio import APIClient, Regions, SendPushRequest
client = APIClient("your API key", region=Regions.US)

request = SendPushRequest(
  transactional_message_id="3",
  identifiers={
    "id": "2",
  }
)

response = client.send_push(request)
print(response)

curl --request POST \
  --url https://api.customer.io/v1/send/email \
  --header 'content-type: application/json' \
  --data '{
    "transactional_message_id": 44,
    "to": "cool.person@example.com",
    "from": "override-templated-address@example.com",
    "subject": "Did you really login from a new location?",
    "identifiers": {
        "email": "cool.person@example.com"
    },
    "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
}'

Update the content of your email

You can update the contents of your message through our user interface or API.

We’ve 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 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"}'