Outbound Email

Mailchimp Transactional is first and foremost about sending email. This documentation outlines some of the most common issues people face when setting up and sending transactional outbound messages for things like confirmations, password resets, and more.

You can also create highly customized 1-to-1 transactional messages that are triggered by specific users’ actions. Though this is similar to Mailchimp’s Automation feature, in Mailchimp Transactional, all logic is handled by your own system; data is only passed to Mailchimp at the time of your API send request or SMTP message.

Sending messages

To send an email using the Transactional API, use the /messages/send or /messages/send-template endpoints. You’ll have to set up and authenticate a domain first—specifically, with DKIM records, which are required. 

For full information on authentication setup, see the Authentication and Delivery docs; to walk through the process with code samples, see the Send Your First Transactional Email guide. 

The backlog

The number of messages you can send in a given time is determined by your pricing plan as well as your hourly quota, which is based on your sending reputation. If you exceed your quota, unsent messages will be placed in the backlog.

When this happens,  you’ll see the status as queued with a queued_reason explaining why. 

We backlog emails instead of sending them in the following cases. 

• Hourly quota exhausted - You’ve sent all the emails your hourly quota allows. We’ll begin processing the backlog in the next hour.

• Free trial sends exhausted - You’ve sent all the emails your demo account allows. You’ll need to upgrade to a paid account to send more emails. Learn more about the Transactional Email demo.

• Monthly limit reached - You’ve sent all the emails your plan allows. To send the queued emails immediately, you’ll need to upgrade your monthly plan or purchase top-off emails. Otherwise, we’ll send the queued emails when your plan rolls into its next month. 

• User has paused sending - You’ve manually paused sending for your account. You can pause and unpause sending by clicking Pause sending on the Dashboard.

• Admin has suspended sending - We’ve suspended your Mailchimp account or Transactional account. Contact Customer Support for more information. 

• Sending is backlogged for technical reasons - We might also backlog emails for other various reasons, typically due to infrastructure-related issues. This is rare and should happen infrequently.

To clear your backlog, click the trash can icon beneath your sends. Clearing the backlog can’t be undone, and all messages queued in the backlog will be removed.

There are other cases where you may see the message response status as queued but the message is not placed in the backlog. These cases include:

• Emails sent with attachments

• Emails with more than 10 recipients

We queue these messages to process asynchronously, and will send them as soon as possible, usually within seconds.

Prioritization

If you have a campaign or a large batch of emails queued in the backlog, Mailchimp Transactional reserves an extra 5% of your hourly quota so more critical emails, such as password resets or order confirmations, can send without delay.

To flag important messages and give them priority in the queue, use the important parameter in your API calls or the X-MC-Important header if you’re sending via SMTP, with the value set to true.

Via SMTP, you can send to up to 1,000 recipients at a time. If you’re sending messages to more recipients, simultaneous and subsequent connections are permitted.

Via the API, there’s no recipient limitation, but the JSON provided per API call must be less than 10MB. We strongly recommend smaller recipient batches for easier troubleshooting.

To control whether recipients can see each others’ information in the To header of your messages, navigate to the Sending Defaults page and select or unselect Expose The List Of Recipients When Sending To Multiple Addresses. You can override these global settings on a per-message basis with the preserve_recipients parameter in your API calls, or with the X-MC-PreserveRecipients SMTP header.

Mailchimp Transactional lets you specify when a message should be sent; messages will be stored until that time and then sent automatically. We’ll try to deliver them as close as possible to the time indicated, but to-the-second precision typically isn’t possible. A scheduled email counts towards the monthly send total at the time it’s sent, not when it’s scheduled.

You can schedule a message up to one year from the date that you're scheduling the message.

To schedule a message, use the send_at parameter (API) or the X-MC-SendAt header (SMTP). Both the API and SMTP accept a UTC timestamp in YYYY-MM-DD HH:MM:SS format. The message ID returned by the send call can be used to cancel or reschedule the message.

messages/reschedule lets you change when a scheduled message will be delivered, and messages/cancel-schedule deletes a scheduled message—which will also prevent that message from counting towards your monthly send total.

If the message content is still available, you can resend an individual email that has soft-bounced or has been delivered. Messages that have been rejected cannot be resent, since the content of rejected messages isn’t processed or stored in Mailchimp Transactional. Messages cannot be resent in bulk, and resending a message will consume send credits.

To resend a message, navigate to Activity and find the message you want to resend. By default, the message will be resent to the original email address; to change that, you can modify the email address field in the modal window.

If the Resend button isn’t available, the message can’t be resent—this usually means the email hard-bounced, the recipient unsubscribed or marked the message as spam, or the content storage period has expired.

Mailchimp Transactional will show you how many times an email has been resent under the Resend button for the original message; click on that number to see date and time details for resent emails.

Some email clients won’t display HTML emails, or your recipients may have disabled HTML emails in their mail settings, so it’s good practice to include a fallback plain-text version of your message. Conversely, open tracking is only available with HTML emails, so if you’re sending plain text but want to track opens, you’ll want to generate an HTML version as well.

You can generate both HTML and plain-text versions of your emails by checking the respective boxes in Sending Defaults. To add either on a per-message basis, you can use the auto_text and auto_html parameters (API), or the X-MC-AutoText and X-MC-AutoHTML headers (SMTP). 

Some email clients support only a subset of valid HTML, so in most cases CSS should be handled using inline styles. Rather than inlining your CSS manually before sending your HTML to Mailchimp Transactional, we provide a sending option to inline CSS automatically at the time of send (as long as your message is 256KB or smaller). 

To enable automatic inlining, select Inline CSS Styles In HTML Emails on the Sending Defaults page. You can also enable it on a per-message basis using the inline_css option (API) or X-MC-InlineCSS header (SMTP), or set it conditionally using the rules engine.

CSS inlining can be an intensive process and since Transactional Email is designed to get your emails out as quickly as possible, the additional processing time to inline CSS can affect delivery speeds. If you have a larger template or HTML document, it’s best to inline your styles manually or by using a separate CSS inlining tool as a part of your sending process.

Mailchimp Transactional allows attachments, but the total message size cannot exceed 25MB. There is no specific limit for individual attachments, just the total size of the message. Because attachments are Base64-encoded, this means that they will be 1/3 larger when sending than they are on disk.

Messages that include attachments are processed through a series of virus-scanning engines to make sure the attachments are safe for recipients.

You can include images in your messages, though you cannot upload them to templates, and Mailchimp Transactional does not store images. We recommend that you host images on your own site instead of general sharing services; file- and photo-hosting sites could have other users’ content on them and could be more likely to be flagged by spam filters or lead to failed content reviews.

To embed an image hosted at a static URL in your message HTML or template, use a standard img tag:

<img src="http://example.com/image.jpg" alt="My image" />

Or use merge tags to insert image file names dynamically: 

<img src="http://example.com/*|IMAGENAME|*" alt="My image" />

You can also include images as inline attachments with API calls using the images parameter. You must provide the image name (Content ID), the content (as a base64 encoded string), and the image MIME type. Reference the image name in the src parameter in your HTML content: <img src="cid:image_name">

For most SMTP libraries, inline images are handled automatically. For example, if you insert an image inline, an img tag is added which then references the Content ID of the image that’s attached. How to add inline images will depend on the SMTP library being used.

While the nature of transactional email means users generally won’t have reason to unsubscribe, it’s good practice to include an unsubscribe link—not including one can lead to more spam complaints.

You can add an automatic unsubscribe link with a merge tag or add an unsubscribe footer with Sending Defaults or the rules engine. When you include an automatic unsubscribe link, your emails will also include the List-Unsubscribe header by default. If you manage your own unsubscribe process, you can provide your own List-Unsubscribe header in your SMTP message or API call instead.

Unsubscribe merge tag

The unsubscribe merge tag consists of the word UNSUB, followed by a colon, and then a full website address (ideally https://). Recipients will be redirected to this website address when they click the link, so it should be a valid page on your site. 

For example:

*|UNSUB:http://example.com/unsub|*

If a recipient clicks the generated link, the message status changes to Unsubscribed and the recipient's address will be added to your Rejection Denylist. The redirect URL will be appended to include two query string parameters that can be used for processing the unsubscribe in your own system or database:

• md_id: The _id, as provided in the API call and webhooks of the specific message where the unsubscribe link was clicked

• md_email: A URL-encoded and obfuscated version of the recipient’s email address. If displayed, the email is shown using the format X****@x***.***.

The unsubscribe merge tag generates only the URL to unsubscribe and can be used in both HTML and text emails. In HTML, you might construct a clickable link for recipients to unsubscribe like this:

<a href="*|UNSUB:http://example.com/unsub|*">Click here to unsubscribe.</a>

Automatic unsubscribe footer

In Sending Defaults, select Add Unsubscribe Footer to automatically add the footer to your emails. This setting will apply globally, but if you’d rather include it conditionally, use the rules engine. 

The footer includes information about the address the email was sent to, along with an unsubscribe link. You do not need a website to process these unsubscribes—Mailchimp will direct the recipient to an unbranded web page confirming that the recipient address has been unsubscribed.

If your emails are reaching Mailchimp Transactional but not being sent, checking your recent API calls can be a good way to troubleshoot. 

To view recent API calls, navigate to Settings and click API Logs. You’ll see the 100 most recent successful and the 100 most recent failed calls, and you can click on any of them for more details. You can also search by keyword, API key used, or use the Search Logs box.

For each API call, you’ll see:

• The date and time the request was received (in your local timezone based on your OS or browser settings)

• The method used—this corresponds to the API endpoint that was called, e.g., messages/send

• The IP address that made the API request.

• The call time for the request—measured in milliseconds (ms) or seconds (s)—recorded from the moment we receive the request to the moment we’ve prepared the response to send back to the caller

• The user agent used to make the request 

• A link to view the entire request and response