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
|
{"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
|
{"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.json
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":"example key","query":"email:gmail.com","date_from":"2013-01-01","date_to":"2013-01-02","tags":["password-reset","welcome"],"senders":["sender@example.com"],"api_keys":["PmmzuovUZMPJsa73o3jjCw"],"limit":100}
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"}}]
Example Error Response JSON
{"status":"error","code":-2,"name":"ServiceUnavailable","message":"Service Temporarily Unavailable"}
Parameters |
key*
string
|
a valid api key
|
query
string
|
search terms to find matching messages
|
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
|
api_keys
array
|
an array of API keys to narrow the search to, will return messages sent by ANY of the keys
|
limit
integer
|
the maximum number of results to return, defaults to 100, 1000 is the maximum
|
Return Value |
array |
of structs for each matching message
return[]
struct
|
the information for a single matching 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 |
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/search-time-series.json
Search the content of recently sent messages and return the aggregated hourly stats for matching messages
{"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
{"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
{"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
{"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
|
{"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.
{"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.
{"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.
{"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.
|