Mailchimp Developer Homepage

Fundamentals

The basics

Mailchimp Transactional is a powerful email delivery service that lets you send personalized, one-to-one emails like password resets, order confirmations, and welcome messages. 

To sign up for Mailchimp Transactional, you need a Mailchimp account. You can try the Mailchimp Transactional demo with any level account, but to use the full version you must have a Standard or Premium account

anchor to sending-via-the-api-or-smtpSending via the API or SMTP 

Once you’ve set up your account and verified your domain, there are two routes to start sending: via the Transactional API or with SMTP integration. If you’re already sending transactional emails through SMTP, you can typically change your SMTP credentials to Mailchimp Transactional’s and begin sending immediately. SMTP is a sending-only protocol, but the Transactional API allows you not only to send but also to view and parse reporting data in your own app or system. The API also offers more comprehensive integration, so it reports more specific errors when sending.

There are no discernible differences in terms of deliverability between using the API or SMTP integration—the actual process Mailchimp Transactional uses to send your emails is the same for both, and ISPs will see both your information and Mailchimp’s in your message headers.

Generally, the Transactional API is faster in terms of accepting mail because HTTP is less “chatty” than SMTP, but we’ve taken steps to help reduce the latency when you’re using SMTP, so you may not see as much of a difference between the two. If speed is a consideration, you may want to test both, including any content generation, to see which is faster overall for your particular environment.

Mailchimp Transactional offers many ways to customize how your emails are tracked, tagged, and more. Throughout the documentation, you’ll often see parallel instructions, one using the API, and one using SMTP. To review the full list of Transactional API endpoints and parameters, see the API Reference; for a complete list of custom SMTP headers, check out the SMTP docs.

anchor to using-mailchimp-transactionalUsing Mailchimp Transactional

Whether you send via the API or SMTP, Mailchimp Transactional has a host of features to help optimize, track, and analyze your sends. 

To learn the basics of sending—like scheduling, prioritization, and unsubscribing—check out the outbound email docs. You can create templates that let you reuse email designs and inject dynamic content with one of several merge languages. And if you need to send email on behalf of multiple clients or separate sending for different users, you can set up subaccounts as well.

Once you’ve started sending, you can monitor your reputation, which is partly determined by your ratio of bounces, spam complaints, and other factors to overall sending. You can also add tags and metadata to help track your messages, alongside other reporting tools like open and click tracking, Google Analytics, and more. 

And finally, to receive and respond to information about your email events, you can set up inbound email processing as well as webhooks, or set up conditional rules that let you take specific actions when events or messages meet criteria you’ve set.

anchor to contact-listsContact lists

Contact lists cannot be uploaded or stored in Mailchimp Transactional. Your application's database should serve as the source of truth for user emails and contact lists; you will only pass that information to Mailchimp in your API request or SMTP message when you’re ready to send an email.

Note: If you’re looking for a service that provides list management and the ability to create and track bulk emails, you should use Mailchimp, rather than Mailchimp Transactional. View our Acceptable Use Policy for additional details.

anchor to mailchimp-transactional-and-mandrillMailchimp Transactional and Mandrill

Throughout the Mailchimp Transactional guides and docs, you may notice the occasional reference to the product’s original name, Mandrill. Mandrill is in the process of being fully integrated into Mailchimp proper, and while this process is ongoing, you will from time to time see artifacts of this migration.

Getting started

If you have a Mailchimp Standard plan or higher, you can enable Mailchimp Transactional from the Billing section of your account; if you don’t have a Mailchimp account, you can sign up directly for Mailchimp Transactional. 

Once you enter your information, you can adjust how many blocks of emails you want to purchase each month, as well as set your preferences for when you run low on emails. You can change these settings at any time on the Transactional page of your Mailchimp account.

anchor to launch-mailchimp-transactionalLaunch Mailchimp Transactional 

The fastest way to launch Mailchimp Transactional is to go directly to https://mandrillapp.com/ and log in. You can also click the Launch App button on the Transactional page of your Mailchimp account.

Once your account is up and running, you’ll need to do a few things before you can start sending messages. 

anchor to set-up-your-sending-domainSet up your sending domain

Before you start sending, you’ll need to authenticate your sending domain, configure your DNS, add SPF and DKIM records, and verify ownership of your domain. While the authentication docs will give you everything you need to get started, you can also walk through the process with the Send Your First Email guide. 

anchor to sending-messagesSending messages

Whether you’re sending via the API or SMTP, you’ll need to generate an API key first. You can do that via the Settings page in the app. That’s also where you can get your SMTP credentials; for more information about setting up SMTP, see the SMTP docs. If you’re sending via the API, the Quick Start walks through installing your preferred client library and making your first API call. After that, you’ll be ready to start sending messages.

API conventions

While you’re reviewing the API reference for an overview of endpoints and parameters, it’s also a good idea to familiarize yourself with some of the basics of the API itself, outlined below. 

Note: These API conventions are less relevant if you choose to use one of our client libraries; for more information, check out the Tools page.

anchor to root-api-endpointRoot API endpoint

All API URLs listed in this documentation are relative to https://mandrillapp.com/api/1.0/. All methods are accessed via https://mandrillapp.com/api/1.0/SOME_METHOD.OUTPUT_FORMAT

For example, the /users/ping call is reachable at https://mandrillapp.com/api/1.0/users/ping.json.

anchor to restful-deviationsRESTful deviations

The Transactional API is mostly RESTful, but there are a couple of deviations:

  • All API calls should be made with HTTP POST.

  • You can consider any non-200 HTTP response code an error—the returned data will contain more detailed information.

anchor to passing-request-dataPassing request data

Request data is passed to the API by posting JSON objects to the API endpoints with the appropriate parameters. The documentation for each API call contains more detail on the parameters accepted by the call. As an alternative, you can also use HTTP POST parameters, just like submitting an HTML form, but JSON objects are recommended.

anchor to authenticationAuthentication

You can authenticate requests to the Transactional API using your API key. All requests to the Transactional API are POST requests, and at minimum, you’ll need to include a key parameter in the JSON body of your POST request to authenticate the API call, like so:

Authenticate your API call

JSON
{
  // ...the rest of your payload, as needed
  "key": "YOUR_TRANSACTIONAL_API_KEY"
}

anchor to output-formatsOutput formats

We support four output formats. To use any of them, simply replace the OUTPUT_FORMAT file extension in the API URL with one of:

  • json (default)

  • xml

  • yaml

  • php

Regardless of the output format, inputs are only accepted as JSON objects or HTTP POST parameters.

Account features

You can manage account alerts, modify access, and more directly in the Mailchimp Transactional app. Issues around billing—including monitoring and adjusting your monthly message blocks—should be handled in your main Mailchimp account.

anchor to account-alertsAccount alerts

There are five types of alerts in Mailchimp Transactional, several of which are turned on by default in every new account.

AlertDescription

Poor Reputation

Your account reputation has dropped to Poor

Tag Reputation

A tag’s reputation has dropped to Poor

Subaccount Reputation

A subaccount’s reputation has dropped to Poor

Webhook Failure

A webhook has generated an error when posting an event

Backlog Size

You’ve exceeded your hourly quota and your backlog queue size has risen above the thresholds you configured

You can add or delete new alerts, as well as modify the ones you receive, on the Alerts page of your account. 

anchor to create-and-modify-alertsCreate and modify alerts

Alerts are conditional if/then statements, and you can modify which ones you receive as well as the way you receive them: 

To create a new alert, navigate to the Alerts page of your account, choose the alert you want from the drop-down menu, and click Create Alert

You can send alerts to the primary account contact or a custom email address. You can send SMS alerts to phone numbers in the United States, the United Kingdom, Canada, and some Caribbean islands.

anchor to view-sent-alertsView sent alerts

Mailchimp Transactional keeps a brief log of recent alerts, including the SMS numbers or email addresses where alerts were sent, the alert type, and the date and time they were sent. You’ll see them on the Alerts page once you have a sending history. 

Information used to trigger alerts for backlog size and account reputation is pulled once every hour; tag reputation information is pulled once a day. Webhook alerts are pushed in real time. 

anchor to pause-and-delete-alertsPause and delete alerts

To delete an alert, choose the one you want to remove, click the Edit drop-down, and click Delete. Deleting an alert will also delete the corresponding log of recent instances of the alert. 

You can also pause alerts instead of deleting them entirely: use the on/off toggle on the alert you want to pause. While an alert is paused, Mailchimp Transactional will not send you email notifications for that alert.

anchor to account-activity-emailsAccount activity emails

On the Username & Contact Info page, you can choose to send daily and/or weekly account activity emails to your primary account contact address. Daily emails show the previous day’s stats, while weekly emails are sent each Monday and show your stats from the previous week.

anchor to multiple-usersMultiple users

Since you access Mailchimp Transactional through your main Mailchimp login, you can, like in the rest of Mailchimp, set up multiple user logins. Unlike your main Mailchimp account, however, Mailchimp Transactional does not support different levels of access within the account: all Admins and Owners will have full access, and everyone else will have no access. 

You can manage multi-user access by generating multiple API keys and limiting privileges per key. To manage API keys, see the SMTP & API Info page in the app.

If clients or other team members need to access reporting information, instead of granting access, you can use the Transactional API, webhooks, or activity exports to pull out relevant data and create custom reports for them.

anchor to account-securityAccount security

The Account Security page shows the list of IP addresses that have accessed the account, along with the location, time, and date that they first and last accessed the account. Additionally, we log the access point—API, SMTP, or Web—used to login to the application.

Test mode

Mailchimp Transactional has a test mode that lets you experiment and refine integrations for bounce and complaint handling without actually sending email. Test mode messages don’t count towards your monthly send totals and won’t damage your account reputation by forcing bounces or spam complaints.

anchor to test-api-keysTest API keys

Before you can send emails in test mode, you’ll need a test API key—a limited key that interacts with your account only in test mode. No emails are actually sent when you use a test API key for sending. Emails sent with a test API key are visible in the web interface when in test mode, but not while viewing the account normally.

To create a test API key, navigate to Settings and click + New API Key. After you’ve entered a description and selected the Test Key checkbox, click Create API Key.

anchor to switch-to-test-modeSwitch to test mode

In the app, hover over your username and choose the option to switch to test mode. In test mode, the color of the header bar changes, and only activity for emails sent in test mode will be displayed.

Switching to test mode doesn’t affect emails sent with non-test API keys—those emails will send normally.

anchor to generating-test-bounces-spam-complaints-and-rejectionsGenerating test bounces, spam complaints, and rejections

Since no sending occurs when you use a test API key or send a message in test mode, you won’t generate bounces, rejects, or spam complaints directly; instead, you have to trigger them manually. 

To test webhooks for certain types of events, send emails to these addresses using a test API key:

Email AddressEvent

reject@test.mandrillapp.com

Rejected email

hard_bounce@test.mandrillapp.com

Hard-bounced email

soft_bounce@test.mandrillapp.com

Soft-bounced email

spam@test.mandrillapp.com

Spam complaint

Emails sent in test mode are specifically designed not to send, and won’t affect your account reputation.

Support

Email support is available Monday through Friday between 9am and 5pm EST. When you’re logged in, click on the Support link at the bottom of any page to submit your request.