Transactional FAQ
UpdatedThis page contains answers to frequently asked questions about our transactional API.
Is your question not answered here?
If you have any questions or feedback not covered on this page or in our transactional API documentation, let us know at product@customer.io!
Does the transactional API cost extra?
No! You can start sending transactional messages immediately alongside your other messages.
When should I use the ‘disable message retention’ setting?
You probably want to disable message retention to concealing sensitive content, like password reset tokens. This setting prevents us from retaining and showing the contents of messages when you view sent deliveriesThe instance of a message sent to a person. When you set up a message, you determine an audience for your message. Each individual “send”—the version of a message sent to a single member of your audience—is a delivery. or when you retrieve messages via API. Instead, you’ll see this:
When should I use the transactional API vs event-triggered campaigns?
A transactional message is typically a single message that a person has implicitly requests—even if they’ve unsubscribed from your marketing messages. These are things like:
- Receipts
- Password reset requests
- Account alerts
For emails that require multiple messages (like a double-opt in) or branching (e.g. multiple channels or A/B testing), you should using event-triggered campaigns.
When should I use the transactional API vs API-triggered Broadcasts?
API triggered broadcasts are optimized for sends that go to many people at a time (ie marketing blasts). These broadcasts can be configured to send to an entire segment(s) at a time, and are thus limited to a rate of 1 request/10 seconds, with dedicated messaging queues to manage the high volume.
The transactional API is optimized to send transactional messages to one recipient at a time (ie order confirmations), and should not be used to send marketing blasts. They have a limit of 15 total recipients across To and BCC fields, a higher rate limit of 100 requests/second, and also have dedicated sending lanes to ensure a quick delivery.
How do I send a transactional message supporting multiple languages?
All you have to do is set your 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. Attributes are analogous to traits in Data Pipelines. and then you can add languages to your transactional message template. When you send a message, we’ll match your audience’s attribute to the languages in your template. If a person’s attribute matches one of the languages, they’ll get the appropriate localization; if they don’t, they’ll get the default message.
Learn more about localized transactional messages.
How many people can I message within a single transactional API call?
A single API request can contain a maximum of 15 recipients. This includes all recipients across both the To and BCC fields.
How do I use the transactional API with a custom SMTP server?
If you have configured a custom SMTP server and wish to use an unauthenticated sending domain, you’ll need to contact us at win@customer.io. We’ll manually authenticate the record after confirming that you own the sending domain.
Can I send transactional messages across multiple channels?
We currently support transactional messages for email and push notification channels. If you want to send “transactional” messages to another channel, you can use an event-triggered campaign, potentially with branches.
Why can’t I CC someone on an email?
With Customer.io’s profile-based messaging approach, we don’t include Carbon Copy (CC) options across the platform because of potential complications in open and link tracking. If you truly need to CC someone on a transactional message, add additional addresses to the TO or BCC fields.
Can I A/B test transactional messages?
No. If you need to run an A/B test, try sending an event-triggered campaign.
Can I use the transactional API to send SMS messages?
No. To send transactional-type SMS, use event-triggered campaigns.
Can I use the transactional API to send bulk marketing sends?
No. The transactional API is not optimized for bulk marketing sends, nor should you use our transactional IP pool or your transactional domain to send marketing messages. Use API-triggered broadcasts instead.
What attachment file types are forbidden?
bat, bin, chm, com, cpl, crt, exe, hlp, hta, inf, ins, isp, jse, lnk, mdb, msc, msi, msp, mst, pcd, pif, reg, scr, sct, shs, vbe, vba, vbs, wsf, wsh, wsl
What headers are reserved and cannot be overwritten in the API request?
Authentication-Results, Auto-Submitted, Content-Alias, Content-Base, Content-Disposition, Content-ID, Content-Identifier, Content-Length, Content-Transfer-Encoding, Content-Type, Encoding, Lines, Mail-System-Version, Mailer, Mime-Version, Originating-Client, Received, Received-SPF, Return-Path, VBR-Info, X-Mailer, X-Report-Abuse-To
Can I copy transactional messages across workspaces?
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.
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.
