> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt). > Last updated: September 1, 2026 > To take actions in Customer.io from an agent, use the [Customer.io CLI](https://docs.customer.io/ai/cli/get-started.md) or the [MCP server](https://docs.customer.io/ai/mcp/get-started.md). # Set custom email headers Email headers specify specific sending and return options for an email. When sending via SMTP, you can use custom headers to do a great many things: customize messages, tag them, track them, or control specific behaviors. For example: * Set the `X-Mailgun-Tag` header if you’re using Mailgun’s “Topic” subscription functionality * Set your own `List-Unsubscribe` header for specific emails (if you use our unsubscribe link, we add this header automatically) * Stop emails from being shown as a thread by Gmail with the `X-Entity-Ref-ID` header * Use `X-Auto-Response-Suppress:OOF` to suppress auto-replies from Exchange servers ## Adding, editing, and removing custom headers You’ll find the custom headers option in the email composer. Add them by clicking the **Add Custom** link to the right of the Headers: ![image.png](https://docs.customer.io/images/image(257).png) Here’s an example of an added item: ![image.png](https://docs.customer.io/images/image(258).png) You can add **CC** recipients to your emails, along with Reply-to and BCC. CC recipients are visible to everyone who receives the email. 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. ## Handling automatic replies The `Reply-To` header is for replies that a person composes and sends. But automatic replies—like out-of-office and vacation responses—follow standard email conventions rather than your `Reply-To` header. The recipient’s mail server typically directs these responses to the Return-Path, the envelope sender, rather than the `Reply-To` address. That means that if you set a `Reply-To` address, it likely won’t receive automatic replies. If you want to stop automatic replies from Exchange servers, set the `X-Auto-Response-Suppress:OOF` header (see the example at the top of this page). ## Errors There are a few guidelines: * You can add up to four custom headers at a time, in addition to Reply-to, CC, BCC, and Subject. * Your header’s name can’t be blank, but the value can be. * There are some headers you can’t use (see “Denylisted headers” below) * You can use Liquid here! If there are errors, you’ll see them in the ‘Review Errors’ modal. When there’s a problem with your headers, our ‘Review Errors’ button animates: ![error.gif](https://docs.customer.io/images/error.gif) And we show you an indicator on the relevant header. ![image.png](https://docs.customer.io/images/image(259).png) Then, you can review your errors in the resulting modal: It looks like this: ![image.png](https://docs.customer.io/images/image(260).png) If you’re concerned about how to deal with a specific error here, you should be able to find it in our our [Composer Errors documentation](/messaging/liquid/composer-errors/). ## Denylisted headers There are some headers that we need to keep control of at Customer.io: * Message data such as `Subject` or `To` * MIME headers which dictate email formatting, as well as Return Path information (`Received` or `Return-Path`): these are generated by our servers at time of delivery * Mail client information tags, such as `X-Mailer`: Customer.io needs to set `X-Mailer` and `X-Report-Abuse-To`, to allow receiving services to notify us of bad Authentication-Results ### The full list: Message data MIME Return Path Information Client-specific `Message-ID` `Mime-Version` `Received` `Mail-System-Version` `Date` `Content-ID` `Return-Path` `Mailer` `From` `Content-Base` `Authentication-Results` `Originating-Client` `Subject` `Content-Alias` `Received-SPF` `X-Mailer` `To` `Content-Identifier` `Auto-Submitted` `X-Report-Abuse-To` `Reply-To` `Content-Length` `VBR-Info` `CC` `Lines` `Content-Type` `Content-Disposition` `Content-Transfer-Encoding` `Encoding` ### Provider-specific headers **X-SMTPAPI (SendGrid):** If you send an `X-SMTPAPI` header, we reserve the use of the `email_id` [unique argument ↗](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/unique-arguments) to support message tracking and reporting, the remainder of your header will be passed through to Sendgrid unchanged. ## Feedback? This is a fairly advanced feature, and we want to make it as useful as possible, and help you better track and customize your emails. If you have any questions or feedback on this feature, [please let us know](https://customer.io/contact/)! ©2026 Peaberry Software, Inc. [Status](https://status.customerio.com/) [Terms of Service](https://customer.io/legal/terms-of-service/) [Privacy Policy](https://customer.io/legal/privacy-policy/) [](https://www.linkedin.com/company/customer-io)[](https://twitter.com/customerio)[](https://www.youtube.com/channel/UCkCaWdezRoa8ZyR9pEVaipA)[](https://www.instagram.com/customer.io/)