JSON

Choose Language

Messages Calls

/messages/send.json

Send a new transactional message through Mandrill

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

Example Request JSON

{"key":"example key","message":{"html":"<p>Example HTML content<\/p>","text":"Example text content","subject":"example subject","from_email":"message.from_email@example.com","from_name":"Example Name","to":[{"email":"recipient.email@example.com","name":"Recipient Name","type":"to"}],"headers":{"Reply-To":"message.reply@example.com"},"important":false,"track_opens":null,"track_clicks":null,"auto_text":null,"auto_html":null,"inline_css":null,"url_strip_qs":null,"preserve_recipients":null,"view_content_link":null,"bcc_address":"message.bcc_address@example.com","tracking_domain":null,"signing_domain":null,"return_path_domain":null,"merge":true,"merge_language":"mailchimp","global_merge_vars":[{"name":"merge1","content":"merge1 content"}],"merge_vars":[{"rcpt":"recipient.email@example.com","vars":[{"name":"merge2","content":"merge2 content"}]}],"tags":["password-resets"],"subaccount":"customer-123","google_analytics_domains":["example.com"],"google_analytics_campaign":"message.from_email@example.com","metadata":{"website":"www.example.com"},"recipient_metadata":[{"rcpt":"recipient.email@example.com","values":{"user_id":123456}}],"attachments":[{"type":"text\/plain","name":"myfile.txt","content":"ZXhhbXBsZSBmaWxl"}],"images":[{"type":"image\/png","name":"IMAGECID","content":"ZXhhbXBsZSBmaWxl"}]},"async":false,"ip_pool":"Main Pool","send_at":"example send_at"}

Example Response JSON

[{"email":"recipient.email@example.com","status":"sent","reject_reason":"hard-bounce","_id":"abc123abc123abc123abc123abc123"}]

Example Error Response JSON

{"status":"error","code":12,"name":"Unknown_Subaccount","message":"No subaccount exists with the id 'customer-123'"}
Parameters
key* string a valid API key
message* struct the information on the message to send
html string the full HTML content to be sent
text string optional full text content to be sent
subject string the message subject
from_email string the sender email address.
email
from_name string optional from name to be used
to array an array of recipient information.
to[] struct a single recipient's information.
email* string the email address of the recipient
required
name string the optional display name to use for the recipient
type string the header type to use for the recipient, defaults to "to" if not provided
oneof(to, cc, bcc)
headers struct optional extra headers to add to the message (most headers are allowed)
important boolean whether or not this message is important, and should be delivered ahead of non-important messages
track_opens boolean whether or not to turn on open tracking for the message
track_clicks boolean whether or not to turn on click tracking for the message
auto_text boolean whether or not to automatically generate a text part for messages that are not given text
auto_html boolean whether or not to automatically generate an HTML part for messages that are not given HTML
inline_css boolean whether or not to automatically inline all CSS styles provided in the message HTML - only for HTML documents less than 256KB in size
url_strip_qs boolean whether or not to strip the query string from URLs when aggregating tracked URL data
preserve_recipients boolean whether or not to expose all recipients in to "To" header for each email
view_content_link boolean set to false to remove content logging for sensitive emails
bcc_address string an optional address to receive an exact copy of each recipient's email
email
tracking_domain string a custom domain to use for tracking opens and clicks instead of mandrillapp.com
signing_domain string a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
return_path_domain string a custom domain to use for the messages's return-path
merge boolean whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided.
merge_language string the merge tag language to use when evaluating merge tags, either mailchimp or handlebars
oneof(mailchimp, handlebars)
global_merge_vars array global merge variables to use for all recipients. You can override these per recipient.
global_merge_vars[] struct a single global merge variable
name string the global merge variable's name. Merge variable names are case-insensitive and may not start with _
content mixed the global merge variable's content
merge_vars array per-recipient merge variables, which override global merge variables with the same name.
merge_vars[] struct per-recipient merge variables
rcpt* string the email address of the recipient that the merge variables should apply to
required
vars array the recipient's merge variables
vars[] struct a single merge variable
name string the merge variable's name. Merge variable names are case-insensitive and may not start with _
content mixed the merge variable's content
tags array an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
tags[]* string a single tag - must not start with an underscore
required
subaccount string the unique id of a subaccount for this message - must already exist or will fail with an error
google_analytics_domains array an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.
google_analytics_campaign array|string optional string indicating the value to set for the utm_campaign tracking parameter. If this isn't provided the email's from address will be used instead.
metadata array metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.
recipient_metadata array Per-recipient metadata that will override the global values specified in the metadata parameter.
recipient_metadata[] struct metadata for a single recipient
rcpt string the email address of the recipient that the metadata is associated with
values array an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.
attachments array an array of supported attachments to add to the message
attachments[] struct a single supported attachment
type string the MIME type of the attachment
name string the file name of the attachment
content string the content of the attachment as a base64-encoded string
images array an array of embedded images to add to the message
images[] struct a single embedded image
type string the MIME type of the image - must start with "image/"
name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
content string the content of the image as a base64-encoded string
async boolean enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of "queued" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async.
ip_pool string the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead.
send_at string when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately. An additional fee applies for scheduled email, and this feature is only available to accounts with a positive balance.
Validation: datetime
Return Value
array of structs for each recipient containing the key "email" with the email address, and details of the message status for that recipient
return[] struct the sending results for a single recipient
email string the email address of the recipient
status string the sending status of the recipient - either "sent", "queued", "scheduled", "rejected", or "invalid"
reject_reason string the reason for the rejection if the recipient status is "rejected" - one of "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", or "rule"
_id string the message's unique id
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
PaymentRequired The requested feature requires payment.
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/send-template.json

Send a new transactional message through Mandrill using a template

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

Example Request JSON

{"key":"example key","template_name":"example template_name","template_content":[{"name":"example name","content":"example content"}],"message":{"html":"<p>Example HTML content<\/p>","text":"Example text content","subject":"example subject","from_email":"message.from_email@example.com","from_name":"Example Name","to":[{"email":"recipient.email@example.com","name":"Recipient Name","type":"to"}],"headers":{"Reply-To":"message.reply@example.com"},"important":false,"track_opens":null,"track_clicks":null,"auto_text":null,"auto_html":null,"inline_css":null,"url_strip_qs":null,"preserve_recipients":null,"view_content_link":null,"bcc_address":"message.bcc_address@example.com","tracking_domain":null,"signing_domain":null,"return_path_domain":null,"merge":true,"merge_language":"mailchimp","global_merge_vars":[{"name":"merge1","content":"merge1 content"}],"merge_vars":[{"rcpt":"recipient.email@example.com","vars":[{"name":"merge2","content":"merge2 content"}]}],"tags":["password-resets"],"subaccount":"customer-123","google_analytics_domains":["example.com"],"google_analytics_campaign":"message.from_email@example.com","metadata":{"website":"www.example.com"},"recipient_metadata":[{"rcpt":"recipient.email@example.com","values":{"user_id":123456}}],"attachments":[{"type":"text\/plain","name":"myfile.txt","content":"ZXhhbXBsZSBmaWxl"}],"images":[{"type":"image\/png","name":"IMAGECID","content":"ZXhhbXBsZSBmaWxl"}]},"async":false,"ip_pool":"Main Pool","send_at":"example send_at"}

Example Response JSON

[{"email":"recipient.email@example.com","status":"sent","reject_reason":"hard-bounce","_id":"abc123abc123abc123abc123abc123"}]

Example Error Response JSON

{"status":"error","code":12,"name":"Unknown_Subaccount","message":"No subaccount exists with the id 'customer-123'"}
Parameters
key* string a valid API key
template_name* string the immutable name or slug of a template that exists in the user's account. For backwards-compatibility, the template name may also be used but the immutable slug is preferred.
Validation: required
template_content* array an array of template content to send. Each item in the array should be a struct with two keys - name: the name of the content block to set the content for, and content: the actual content to put into the block
template_content[] struct the injection of a single piece of content into a single editable region
name* string the name of the mc:edit editable region to inject into
required
content* string the content to inject
required
message* struct the other information on the message to send - same as /messages/send, but without the html content
html string optional full HTML content to be sent if not in template
text string optional full text content to be sent
subject string the message subject
from_email string the sender email address.
email
from_name string optional from name to be used
to array an array of recipient information.
to[] struct a single recipient's information.
email* string the email address of the recipient
required
name string the optional display name to use for the recipient
type string the header type to use for the recipient, defaults to "to" if not provided
oneof(to, cc, bcc)
headers struct optional extra headers to add to the message (most headers are allowed)
important boolean whether or not this message is important, and should be delivered ahead of non-important messages
track_opens boolean whether or not to turn on open tracking for the message
track_clicks boolean whether or not to turn on click tracking for the message
auto_text boolean whether or not to automatically generate a text part for messages that are not given text
auto_html boolean whether or not to automatically generate an HTML part for messages that are not given HTML
inline_css boolean whether or not to automatically inline all CSS styles provided in the message HTML - only for HTML documents less than 256KB in size
url_strip_qs boolean whether or not to strip the query string from URLs when aggregating tracked URL data
preserve_recipients boolean whether or not to expose all recipients in to "To" header for each email
view_content_link boolean set to false to remove content logging for sensitive emails
bcc_address string an optional address to receive an exact copy of each recipient's email
email
tracking_domain string a custom domain to use for tracking opens and clicks instead of mandrillapp.com
signing_domain string a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
return_path_domain string a custom domain to use for the messages's return-path
merge boolean whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided.
merge_language string the merge tag language to use when evaluating merge tags, either mailchimp or handlebars
oneof(mailchimp, handlebars)
global_merge_vars array global merge variables to use for all recipients. You can override these per recipient.
global_merge_vars[] struct a single global merge variable
name string the global merge variable's name. Merge variable names are case-insensitive and may not start with _
content mixed the global merge variable's content
merge_vars array per-recipient merge variables, which override global merge variables with the same name.
merge_vars[] struct per-recipient merge variables
rcpt* string the email address of the recipient that the merge variables should apply to
required
vars array the recipient's merge variables
vars[] struct a single merge variable
name string the merge variable's name. Merge variable names are case-insensitive and may not start with _
content mixed the merge variable's content
tags array an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
tags[]* string a single tag - must not start with an underscore
required
subaccount string the unique id of a subaccount for this message - must already exist or will fail with an error
google_analytics_domains array an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.
google_analytics_campaign array|string optional string indicating the value to set for the utm_campaign tracking parameter. If this isn't provided the email's from address will be used instead.
metadata array metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.
recipient_metadata array Per-recipient metadata that will override the global values specified in the metadata parameter.
recipient_metadata[] struct metadata for a single recipient
rcpt string the email address of the recipient that the metadata is associated with
values array an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.
attachments array an array of supported attachments to add to the message
attachments[] struct a single supported attachment
type string the MIME type of the attachment
name string the file name of the attachment
content string the content of the attachment as a base64-encoded string
images array an array of embedded images to add to the message
images[] struct a single embedded image
type string the MIME type of the image - must start with "image/"
name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
content string the content of the image as a base64-encoded string
async boolean enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of "queued" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async.
ip_pool string the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead.
send_at string when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately. An additional fee applies for scheduled email, and this feature is only available to accounts with a positive balance.
Validation: datetime
Return Value
array of structs for each recipient containing the key "email" with the email address, and details of the message status for that recipient
return[] struct the sending results for a single recipient
email string the email address of the recipient
status string the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
reject_reason string the reason for the rejection if the recipient status is "rejected" - one of "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", or "rule"
_id string the message's unique id
Errors
Unknown_Template The requested template does not exist
PaymentRequired The requested feature requires payment.
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/search-time-series.json

Search the content of recently sent messages and return the aggregated hourly stats for matching messages

Example Request JSON

{"key":"example key","query":"email:gmail.com","date_from":"2013-01-01","date_to":"2013-01-02","tags":["password-reset","welcome"],"senders":["sender@example.com"]}

Example Response JSON

[{"time":"2013-01-01 15:00:00","sent":42,"hard_bounces":42,"soft_bounces":42,"rejects":42,"complaints":42,"unsubs":42,"opens":42,"unique_opens":42,"clicks":42,"unique_clicks":42}]

Example Error Response JSON

{"status":"error","code":-2,"name":"ServiceUnavailable","message":"Service Temporarily Unavailable"}
Parameters
key* string a valid api key
query string the search terms to find matching messages for
date_from string start date
Validation: date
date_to string end date
Validation: date
tags array an array of tag names to narrow the search to, will return messages that contain ANY of the tags
senders array an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
Return Value
array the array of history information
return[] struct the stats for a single hour
time string the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
sent integer the number of emails that were sent during the hour
hard_bounces integer the number of emails that hard bounced during the hour
soft_bounces integer the number of emails that soft bounced during the hour
rejects integer the number of emails that were rejected during the hour
complaints integer the number of spam complaints received during the hour
unsubs integer the number of unsubscribes received during the hour
opens integer the number of emails opened during the hour
unique_opens integer the number of unique opens generated by messages sent during the hour
clicks integer the number of tracked URLs clicked during the hour
unique_clicks integer the number of unique clicks generated by messages sent during the hour
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ServiceUnavailable The subsystem providing this API call is down for maintenance
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/info.json

Get the information for a single recently sent message

Example Request JSON

{"key":"example key","id":"abc123abc123abc123abc123"}

Example Response JSON

{"ts":1365190000,"_id":"abc123abc123abc123abc123","sender":"sender@example.com","template":"example-template","subject":"example subject","email":"recipient.email@example.com","tags":["password-reset"],"opens":42,"opens_detail":[{"ts":1365190001,"ip":"55.55.55.55","location":"Georgia, US","ua":"Linux\/Ubuntu\/Chrome\/Chrome 28.0.1500.53"}],"clicks":42,"clicks_detail":[{"ts":1365190001,"url":"http:\/\/www.example.com","ip":"55.55.55.55","location":"Georgia, US","ua":"Linux\/Ubuntu\/Chrome\/Chrome 28.0.1500.53"}],"state":"sent","metadata":{"user_id":"123","website":"www.example.com"},"smtp_events":[{"ts":1365190001,"type":"sent","diag":"250 OK"}]}

Example Error Response JSON

{"status":"error","code":11,"name":"Unknown_Message","message":"No message exists with the id 'McyuzyCS5M3bubeGPP-XVA'"}
Parameters
key* string a valid api key
id* string the unique id of the message to get - passed as the "_id" field in webhooks, send calls, or search calls
Return Value
struct the information for the message
ts integer the Unix timestamp from when this message was sent
_id string the message's unique id
sender string the email address of the sender
template string the unique name of the template used, if any
subject string the message's subject line
email string the recipient email address
tags array list of tags on this message
tags[] string individual tag on this message
opens integer how many times has this message been opened
opens_detail array list of individual opens for the message
opens_detail[] struct information on an individual open
ts integer the unix timestamp from when the message was opened
ip string the IP address that generated the open
location string the approximate region and country that the opening IP is located
ua string the email client or browser data of the open
clicks integer how many times has a link been clicked in this message
clicks_detail array list of individual clicks for the message
clicks_detail[] struct information on an individual click
ts integer the unix timestamp from when the message was clicked
url string the URL that was clicked on
ip string the IP address that generated the click
location string the approximate region and country that the clicking IP is located
ua string the email client or browser data of the click
state string sending status of this message: sent, bounced, rejected
metadata struct any custom metadata provided when the message was sent
smtp_events array a log of up to 3 smtp events for the message
smtp_events[] struct information about a specific smtp event
ts integer the Unix timestamp when the event occured
type string the message's state as a result of this event
diag string the SMTP response from the recipient's server
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Message The provided message id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/content.json

Get the full content of a recently sent message

Example Request JSON

{"key":"example key","id":"abc123abc123abc123abc123"}

Example Response JSON

{"ts":1365190000,"_id":"abc123abc123abc123abc123","from_email":"sender@example.com","from_name":"Sender Name","subject":"example subject","to":{"email":"recipient.email@example.com","name":"Recipient Name"},"tags":["password-reset"],"headers":{"Reply-To":"replies@example.com"},"text":"Some text content","html":"<p>Some HTML content<\/p>","attachments":[{"name":"example.txt","type":"text\/plain","content":"QSBzaW1wbGUgdGV4dCBzdHJpbmcgYXR0YWNobWVudA=="}]}

Example Error Response JSON

{"status":"error","code":11,"name":"Unknown_Message","message":"No message exists with the id 'McyuzyCS5M3bubeGPP-XVA'"}
Parameters
key* string a valid API key
id* string the unique id of the message to get - passed as the "_id" field in webhooks, send calls, or search calls
Return Value
struct the content of the message
ts integer the Unix timestamp from when this message was sent
_id string the message's unique id
from_email string the email address of the sender
from_name string the alias of the sender (if any)
subject string the message's subject line
to struct the message recipient's information
email string the email address of the recipient
name string the alias of the recipient (if any)
tags array list of tags on this message
tags[] string individual tag on this message
headers struct the key-value pairs of the custom MIME headers for the message's main document
text string the text part of the message, if any
html string the HTML part of the message, if any
attachments array an array of any attachments that can be found in the message
attachments[] struct information about an individual attachment
name string the file name of the attachment
type string the MIME type of the attachment
content string the content of the attachment as a base64 encoded string
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Message The provided message id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/parse.json

Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces

Example Request JSON

{"key":"example key","raw_message":"From: sender@example.com\nTo: recipient.email@example.com\nSubject: Some Subject\n\nSome content."}

Example Response JSON

{"subject":"Some Subject","from_email":"sender@example.com","from_name":"Sender Name","to":[{"email":"recipient.email@example.com","name":"Recipient Name"}],"headers":{"Reply-To":"replies@example.com"},"text":"Some text content","html":"<p>Some HTML content<\/p>","attachments":[{"name":"example.txt","type":"text\/plain","binary":false,"content":"example non-binary content"}],"images":[{"name":"IMAGEID","type":"image\/png","content":"ZXhhbXBsZSBmaWxl"}]}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
raw_message* string the full MIME document of an email message
Validation: required
Return Value
struct the parsed message
subject string the subject of the message
from_email string the email address of the sender
from_name string the alias of the sender (if any)
to array an array of any recipients in the message
to[] struct the information on a single recipient
email string the email address of the recipient
name string the alias of the recipient (if any)
headers struct the key-value pairs of the MIME headers for the message's main document
text string the text part of the message, if any
html string the HTML part of the message, if any
attachments array an array of any attachments that can be found in the message
attachments[] struct information about an individual attachment
name string the file name of the attachment
type string the MIME type of the attachment
binary boolean if this is set to true, the attachment is not pure-text, and the content will be base64 encoded
content string the content of the attachment as a text string or a base64 encoded string based on the attachment type
images array an array of any embedded images that can be found in the message
images[] struct information about an individual image
name string the Content-ID of the embedded image
type string the MIME type of the image
content string the content of the image as a base64 encoded string
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/send-raw.json

Take a raw MIME document for a message, and send it exactly as if it were sent through Mandrill's SMTP servers

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

Example Request JSON

{"key":"example key","raw_message":"From: sender@example.com\nTo: recipient.email@example.com\nSubject: Some Subject\n\nSome content.","from_email":"sender@example.com","from_name":"From Name","to":["recipient.email@example.com"],"async":false,"ip_pool":"Main Pool","send_at":"example send_at","return_path_domain":null}

Example Response JSON

[{"email":"recipient.email@example.com","status":"sent","reject_reason":"hard-bounce","_id":"abc123abc123abc123abc123"}]

Example Error Response JSON

{"status":"error","code":12,"name":"Unknown_Subaccount","message":"No subaccount exists with the id 'customer-123'"}
Parameters
key* string a valid API key
raw_message* string the full MIME document of an email message
Validation: required
from_email string|null optionally define the sender address - otherwise we'll use the address found in the provided headers
Validation: email
from_name string|null optionally define the sender alias
to array|null optionally define the recipients to receive the message - otherwise we'll use the To, Cc, and Bcc headers provided in the document
to[] string the email address of the recipient
async boolean enable a background sending mode that is optimized for bulk sending. In async mode, messages/sendRaw will immediately return a status of "queued" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async.
ip_pool string the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead.
send_at string when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately.
Validation: datetime
return_path_domain string a custom domain to use for the messages's return-path
Return Value
array of structs for each recipient containing the key "email" with the email address, and details of the message status for that recipient
return[] struct the sending results for a single recipient
email string the email address of the recipient
status string the sending status of the recipient - either "sent", "queued", "scheduled", "rejected", or "invalid"
reject_reason string the reason for the rejection if the recipient status is "rejected" - one of "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", "unsigned", or "rule"
_id string the message's unique id
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
PaymentRequired The requested feature requires payment.
Unknown_Template The requested template does not exist
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/list-scheduled.json

Queries your scheduled emails.

Example Request JSON

{"key":"example key","to":"test.recipient@example.com"}

Example Response JSON

[{"_id":"I_dtFt2ZNPW5QD9-FaDU1A","created_at":"2013-01-20 12:13:01","send_at":"2021-01-05 12:42:01","from_email":"sender@example.com","to":"test.recipient@example.com","subject":"This is a scheduled email"}]

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
to string an optional recipient address to restrict results to
Validation: email
Return Value
array a list of up to 1000 scheduled emails
return[] struct a scheduled email
_id string the scheduled message id
created_at string the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
send_at string the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
from_email string the email's sender address
to string the email's recipient
subject string the email's subject
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/cancel-scheduled.json

Cancels a scheduled email.

Example Request JSON

{"key":"example key","id":null}

Example Response JSON

{"_id":"I_dtFt2ZNPW5QD9-FaDU1A","created_at":"2013-01-20 12:13:01","send_at":"2021-01-05 12:42:01","from_email":"sender@example.com","to":"test.recipient@example.com","subject":"This is a scheduled email"}

Example Error Response JSON

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid api key
id* string a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled
Return Value
struct information about the scheduled email that was cancelled.
_id string the scheduled message id
created_at string the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
send_at string the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
from_email string the email's sender address
to string the email's recipient
subject string the email's subject
Errors
Unknown_Message The provided message id does not exist.
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/messages/reschedule.json

Reschedules a scheduled email.

Example Request JSON

{"key":"example key","id":"I_dtFt2ZNPW5QD9-FaDU1A","send_at":"20120-06-01 08:15:01"}

Example Response JSON

{"_id":"I_dtFt2ZNPW5QD9-FaDU1A","created_at":"2013-01-20 12:13:01","send_at":"2021-01-05 12:42:01","from_email":"sender@example.com","to":"test.recipient@example.com","subject":"This is a scheduled email"}

Example Error Response JSON

{"status":"error","code":11,"name":"Unknown_Message","message":"No message exists with the id 'McyuzyCS5M3bubeGPP-XVA'"}
Parameters
key* string a valid api key
id* string a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled
send_at* string the new UTC timestamp when the message should sent. Mandrill can't time travel, so if you specify a time in past the message will be sent immediately
Validation: datetime
Return Value
struct information about the scheduled email that was rescheduled.
_id string the scheduled message id
created_at string the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
send_at string the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
from_email string the email's sender address
to string the email's recipient
subject string the email's subject
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Message The provided message id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.