Customer.io

Transactional FAQ

Updated August 18, 2026

This 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 deliveries or when you retrieve messages via API. Instead, you’ll see this:

image.png

When should I use the transactional API vs event-triggered automations?

A transactional message is typically a single message that a profile 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 automations.

When should I use the transactional API vs API-triggered Broadcasts?

API-triggered broadcasts are optimized for sends that go to many profiles 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, CC, and BCC fields, share the higher soft rate limit of our Track and Pipelines ingress (3000 requests per 3 seconds, not strictly enforced), 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 attribute 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 profile’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 profiles 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 the To, CC, 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 CC someone on an email?

Yes. You can add CC recipients in the email composer or by setting the cc key in a transactional API request. CC recipients are visible to everyone who receives the message. CC opens, clicks, and bounces count toward your message’s metrics, but they aren’t broken out per recipient. For example, if a CC recipient opens a message that the original recipient already opened, it counts as a second open on the same send rather than a separate open attributed to the CC recipient.

Can I A/B test transactional messages?

No. If you need to run an A/B test, try sending an event-triggered automation.

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 Transactional landing page, you can see a list of transactional messages. On the right, an arrow points to a menu of options for a single message, including copy to.

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

The modal reads: copy transactional message to another workspace. Below that, a workspace titled Workspace 2 is selected. Below that is the caveat that any settings in this message that do not exist in the destination workspace will reset.

Note

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