Mandrill API Documentation

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

The Mandrill 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

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

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.

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

Official API Clients

The response data for each call will the be encoded in the specified format. Regardless of the output format desired, inputs are only accepted as JSON objects or HTTP POST parameters.

Mandrill has official API clients for the following languages. Click the links below for documentation about each language.

Questions? Problems?

Have you run into difficulties or a method just doesn't seem to work right? Check out our API Support options and we'll be happy to assist you.

API Call Categories

Users Calls info( string key) Return the information about the API-connected user

key) ping( string key) Validate an API key and respond to a ping

key) ping2( string key) Validate an API key and respond to a ping (anal JSON parser version)

key) senders(string key) Return the senders that have tried to use this account, both verified and unverified

Messages Calls send( string key, struct message, boolean async, string ip_pool, string send_at) Note If you signed up for a Mandrill account on or after December 1st, 2015, you must add SPF and DKIM records and verify ownership of your sending domains before you can send email through your account. Mandrill will not send any email from unverified domains or domains without valid SPF and DKIM records, including public domains like gmail.com, yahoo.com, and more.



Custom signing domains are only available to Mandrill accounts created before December 1st, 2015. If you signed up for a new Mandrill account on or after December 1st, 2015, the signing_domain parameter will be ignored.



Mail sent from unverified domains or domains without valid SPF and DKIM records will be rejected with the reject_reason, unsigned.



Learn more about SPF and DKIM, and domain verification Send a new transactional message through Mandrill

key, message, async, ip_pool, send_at) send-template( string key, string template_name, array template_content, struct message, boolean async, string ip_pool, string send_at) Note If you signed up for a Mandrill account on or after December 1st, 2015, you must add SPF and DKIM records and verify ownership of your sending domains before you can send email through your account. Mandrill will not send any email from unverified domains or domains without valid SPF and DKIM records, including public domains like gmail.com, yahoo.com, and more.



Custom signing domains are only available to Mandrill accounts created before December 1st, 2015. If you signed up for a new Mandrill account on or after December 1st, 2015, the signing_domain parameter will be ignored.



Mail sent from unverified domains or domains without valid SPF and DKIM records will be rejected with the reject_reason, unsigned.



Learn more about SPF and DKIM, and domain verification Send a new transactional message through Mandrill using a template

key, template_name, template_content, message, async, ip_pool, send_at) search( string key, string query, string date_from, string date_to, array tags, array senders, array api_keys, integer limit) Search recently sent messages and optionally narrow by date range, tags, senders, and API keys. If no date range is specified, results within the last 7 days are returned. This method may be called up to 20 times per minute. If you need the data more often, you can use /messages/info.json to get the information for a single message, or webhooks to push activity to your own application for querying.

key, query, date_from, date_to, tags, senders, api_keys, limit) search-time-series( string key, string query, string date_from, string date_to, array tags, array senders) Search the content of recently sent messages and return the aggregated hourly stats for matching messages

key, query, date_from, date_to, tags, senders) info( string key, string id) Get the information for a single recently sent message

key, id) content( string key, string id) Get the full content of a recently sent message

key, id) parse( string key, string raw_message) Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces

key, raw_message) send-raw( string key, string raw_message, string|null from_email, string|null from_name, array|null to, boolean async, string ip_pool, string send_at, string return_path_domain) Note If you signed up for a Mandrill account on or after December 1st, 2015, you must add SPF and DKIM records and verify ownership of your sending domains before you can send email through your account. Mandrill will not send any email from unverified domains or domains without valid SPF and DKIM records, including public domains like gmail.com, yahoo.com, and more.



Custom signing domains are only available to Mandrill accounts created before December 1st, 2015. If you signed up for a new Mandrill account on or after December 1st, 2015, the X-MC-SigningDomain header will be ignored.



Mail sent from unverified domains or domains without valid SPF and DKIM records will be rejected with the reject_reason, unsigned.



Learn more about SPF and DKIM, and domain verification Take a raw MIME document for a message, and send it exactly as if it were sent through Mandrill's SMTP servers

key, raw_message, from_email, from_name, to, async, ip_pool, send_at, return_path_domain) list-scheduled( string key, string to) Queries your scheduled emails.

key, to) cancel-scheduled( string key, string id) Cancels a scheduled email.

key, id) reschedule(string key, string id, string send_at) Reschedules a scheduled email.

Tags Calls list( string key) Return all of the user-defined tag information

key) delete( string key, string tag) Deletes a tag permanently. Deleting a tag removes the tag from any messages that have been sent, and also deletes the tag's stats. There is no way to undo this operation, so use it carefully.

key, tag) info( string key, string tag) Return more detailed information about a single tag, including aggregates of recent stats

key, tag) time-series( string key, string tag) Return the recent history (hourly stats for the last 30 days) for a tag

key, tag) all-time-series(string key) Return the recent history (hourly stats for the last 30 days) for all tags

Rejects Calls add( string key, string email, string comment, string subaccount) Adds an email to your email rejection blacklist. Addresses that you add manually will never expire and there is no reputation penalty for removing them from your blacklist. Attempting to blacklist an address that has been whitelisted will have no effect.

key, email, comment, subaccount) list( string key, string email, boolean include_expired, string subaccount) Retrieves your email rejection blacklist. You can provide an email address to limit the results. Returns up to 1000 results. By default, entries that have expired are excluded from the results; set include_expired to true to include them.

key, email, include_expired, subaccount) delete(string key, string email, string subaccount) Deletes an email rejection. There is no limit to how many rejections you can remove from your blacklist, but keep in mind that each deletion has an affect on your reputation.

Whitelists Calls add( string key, string email, string comment) Adds an email to your email rejection whitelist. If the address is currently on your blacklist, that blacklist entry will be removed automatically.

key, email, comment) list( string key, string email) Retrieves your email rejection whitelist. You can provide an email address or search prefix to limit the results. Returns up to 1000 results.

key, email) delete(string key, string email) Removes an email address from the whitelist.

Senders Calls list( string key) Return the senders that have tried to use this account.

key) domains( string key) Returns the sender domains that have been added to this account.

key) add-domain( string key, string domain) Adds a sender domain to your account. Sender domains are added automatically as you send, but you can use this call to add them ahead of time.

key, domain) check-domain( string key, string domain) Checks the SPF and DKIM settings for a domain. If you haven't already added this domain to your account, it will be added automatically.

key, domain) verify-domain( string key, string domain, string mailbox) Sends a verification email in order to verify ownership of a domain. Domain verification is a required step to confirm ownership of a domain. Once a domain has been verified in a Mandrill account, other accounts may not have their messages signed by that domain unless they also verify the domain. This prevents other Mandrill accounts from sending mail signed by your domain.

key, domain, mailbox) info( string key, string address) Return more detailed information about a single sender, including aggregates of recent stats

key, address) time-series(string key, string address) Return the recent history (hourly stats for the last 30 days) for a sender

Urls Calls list( string key) Get the 100 most clicked URLs

key) search( string key, string q) Return the 100 most clicked URLs that match the search query given

key, q) time-series( string key, string url) Return the recent history (hourly stats for the last 30 days) for a url

key, url) tracking-domains( string key) Get the list of tracking domains set up for this account

key) add-tracking-domain( string key, string domain) Add a tracking domain to your account

key, domain) check-tracking-domain(string key, string domain) Checks the CNAME settings for a tracking domain. The domain must have been added already with the add-tracking-domain call

Templates Calls add( string key, string name, string from_email, string from_name, string subject, string code, string text, boolean publish, array labels) Add a new template

key, name, from_email, from_name, subject, code, text, publish, labels) info( string key, string name) Get the information for an existing template

key, name) update( string key, string name, string from_email, string from_name, string subject, string code, string text, boolean publish, array labels) Update the code for an existing template. If null is provided for any fields, the values will remain unchanged.

key, name, from_email, from_name, subject, code, text, publish, labels) publish( string key, string name) Publish the content for the template. Any new messages sent using this template will start using the content that was previously in draft.

key, name) delete( string key, string name) Delete a template

key, name) list( string key, string label) Return a list of all the templates available to this user

key, label) time-series( string key, string name) Return the recent history (hourly stats for the last 30 days) for a template

key, name) render(string key, string template_name, array template_content, array merge_vars) Inject content and optionally merge fields into a template, returning the HTML that results

Webhooks Calls list( string key) Get the list of all webhooks defined on the account

key) add( string key, string url, string description, array events) Add a new webhook

key, url, description, events) info( string key, integer id) Given the ID of an existing webhook, return the data about it

key, id) update( string key, integer id, string url, string description, array events) Update an existing webhook

key, id, url, description, events) delete(string key, integer id) Delete an existing webhook

Subaccounts Calls list( string key, string q) Get the list of subaccounts defined for the account, optionally filtered by a prefix

key, q) add( string key, string id, string name, string notes, integer custom_quota) Add a new subaccount

key, id, name, notes, custom_quota) info( string key, string id) Given the ID of an existing subaccount, return the data about it

key, id) update( string key, string id, string name, string notes, integer custom_quota) Update an existing subaccount

key, id, name, notes, custom_quota) delete( string key, string id) Delete an existing subaccount. Any email related to the subaccount will be saved, but stats will be removed and any future sending calls to this subaccount will fail.

key, id) pause( string key, string id) Pause a subaccount's sending. Any future emails delivered to this subaccount will be queued for a maximum of 3 days until the subaccount is resumed.

key, id) resume(string key, string id) Resume a paused subaccount's sending

Inbound Calls domains( string key) List the domains that have been configured for inbound delivery

key) add-domain( string key, string domain) Add an inbound domain to your account

key, domain) check-domain( string key, string domain) Check the MX settings for an inbound domain. The domain must have already been added with the add-domain call

key, domain) delete-domain( string key, string domain) Delete an inbound domain from the account. All mail will stop routing for this domain immediately.

key, domain) routes( string key, string domain) List the mailbox routes defined for an inbound domain

key, domain) add-route( string key, string domain, string pattern, string url) Add a new mailbox route to an inbound domain

key, domain, pattern, url) update-route( string key, string id, string pattern, string url) Update the pattern or webhook of an existing inbound mailbox route. If null is provided for any fields, the values will remain unchanged.

key, id, pattern, url) delete-route( string key, string id) Delete an existing inbound mailbox route

key, id) send-raw(string key, string raw_message, array|null to, string mail_from, string helo, string client_address) Take a raw MIME document destined for a domain with inbound domains set up, and send it to the inbound hook exactly as if it had been sent over SMTP

Exports Calls info( string key, string id) Returns information about an export job. If the export job's state is 'complete', the returned data will include a URL you can use to fetch the results. Every export job produces a zip archive, but the format of the archive is distinct for each job type. The api calls that initiate exports include more details about the output format for that job type.

key, id) list( string key) Returns a list of your exports.

key) rejects( string key, string notify_email) Begins an export of your rejection blacklist. The blacklist will be exported to a zip archive containing a single file named rejects.csv that includes the following fields: email, reason, detail, created_at, expires_at, last_event_at, expires_at.

key, notify_email) whitelist( string key, string notify_email) Begins an export of your rejection whitelist. The whitelist will be exported to a zip archive containing a single file named whitelist.csv that includes the following fields: email, detail, created_at.

key, notify_email) activity(string key, string notify_email, string date_from, string date_to, array tags, array senders, array states, array api_keys) Begins an export of your activity history. The activity will be exported to a zip archive containing a single file named activity.csv in the same format as you would be able to export from your account's activity view. It includes the following fields: Date, Email Address, Sender, Subject, Status, Tags, Opens, Clicks, Bounce Detail. If you have configured any custom metadata fields, they will be included in the exported data.

Ips Calls list( string key) Lists your dedicated IPs.

key) info( string key, string ip) Retrieves information about a single dedicated ip.

key, ip) provision( string key, boolean warmup, string pool) Requests an additional dedicated IP for your account. Accounts may have one outstanding request at any time, and provisioning requests are processed within 24 hours.

key, warmup, pool) start-warmup( string key, string ip) Begins the warmup process for a dedicated IP. During the warmup process, Mandrill will gradually increase the percentage of your mail that is sent over the warming-up IP, over a period of roughly 30 days. The rest of your mail will be sent over shared IPs or other dedicated IPs in the same pool.

key, ip) cancel-warmup( string key, string ip) Cancels the warmup process for a dedicated IP.

key, ip) set-pool( string key, string ip, string pool, boolean create_pool) Moves a dedicated IP to a different pool.

key, ip, pool, create_pool) delete( string key, string ip) Deletes a dedicated IP. This is permanent and cannot be undone.

key, ip) list-pools( string key) Lists your dedicated IP pools.

key) pool-info( string key, string pool) Describes a single dedicated IP pool.

key, pool) create-pool( string key, string pool) Creates a pool and returns it. If a pool already exists with this name, no action will be performed.

key, pool) delete-pool( string key, string pool) Deletes a pool. A pool must be empty before you can delete it, and you cannot delete your default pool.

key, pool) check-custom-dns( string key, string ip, string domain) Tests whether a domain name is valid for use as the custom reverse DNS for a dedicated IP.

key, ip, domain) set-custom-dns(string key, string ip, string domain) Configures the custom DNS name for a dedicated IP.