Transactional API Conventions

At a glance

The Mailchimp Transactional API is reliable, powerful, and ideal for sending data- and event-driven transactional emails, including targeted e-commerce and personalized one-to-one messages.

This document details some of the high-level conventions for the Mailchimp Transactional API.

Mailchimp Transactional and Mandrill

In this document and throughout the Mailchimp Transactional guides and API reference, you may notice the occasional reference to Mandrill. The Mailchimp Transactional API is the new and improved home for Mandrill, Mailchimp’s once-separate transactional email service. Mandrill is in the process of being rolled more fully into Mailchimp proper, and while this process is ongoing, you will from time to time see artifacts of this migration.

Root API endpoint

All API URLs listed in this documentation are relative to https://mandrillapp.com/api/1.0/. For example, the /users/ping API call is reachable at https://mandrillapp.com/api/1.0/users/ping.json.

RESTful deviations

The Mailchimp Transactional API is a mostly RESTful API. Known caveats:

  • 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

All methods are accessed via: https://mandrillapp.com/api/1.0/SOME-METHOD.OUTPUT_FORMAT

Note: If you’re integrating with the Transactional API using one of the official client libraries, you won’t need to worry about most of the implementation details for the API.

Passing 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 will contain 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.

Authentication

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:

Authentication

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

Output formats

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

  • json (default)

  • xml

  • yaml

  • php

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

Support options

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. 

Documentation

For more information about the features and functionality of Mailchimp Transactional Email, browse the Mailchimp Transactional Knowledge Base