Messages API | Mandrill

/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

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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    message = {'attachments': [{'content': 'ZXhhbXBsZSBmaWxl',
                      'name': 'myfile.txt',
                      'type': 'text/plain'}],
     'auto_html': None,
     'auto_text': None,
     'bcc_address': 'message.bcc_address@example.com',
     'from_email': 'message.from_email@example.com',
     'from_name': 'Example Name',
     'global_merge_vars': [{'content': 'merge1 content', 'name': 'merge1'}],
     'google_analytics_campaign': 'message.from_email@example.com',
     'google_analytics_domains': ['example.com'],
     'headers': {'Reply-To': 'message.reply@example.com'},
     'html': '<p>Example HTML content</p>',
     'images': [{'content': 'ZXhhbXBsZSBmaWxl',
                 'name': 'IMAGECID',
                 'type': 'image/png'}],
     'important': False,
     'inline_css': None,
     'merge': True,
     'merge_language': 'mailchimp',
     'merge_vars': [{'rcpt': 'recipient.email@example.com',
                     'vars': [{'content': 'merge2 content', 'name': 'merge2'}]}],
     'metadata': {'website': 'www.example.com'},
     'preserve_recipients': None,
     'recipient_metadata': [{'rcpt': 'recipient.email@example.com',
                             'values': {'user_id': 123456}}],
     'return_path_domain': None,
     'signing_domain': None,
     'subaccount': 'customer-123',
     'subject': 'example subject',
     'tags': ['password-resets'],
     'text': 'Example text content',
     'to': [{'email': 'recipient.email@example.com',
             'name': 'Recipient Name',
             'type': 'to'}],
     'track_clicks': None,
     'track_opens': None,
     'tracking_domain': None,
     'url_strip_qs': None,
     'view_content_link': None}
    result = mandrill_client.messages.send(message=message, async=False, ip_pool='Main Pool', send_at='example send_at')
    '''
    [{'_id': 'abc123abc123abc123abc123abc123',
      'email': 'recipient.email@example.com',
      'reject_reason': 'hard-bounce',
      'status': 'sent'}]
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.UnknownSubaccountError'> - No subaccount exists with the id 'customer-123'
    raise

Parameters

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

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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    template_content = [{'content': 'example content', 'name': 'example name'}]
    message = {'attachments': [{'content': 'ZXhhbXBsZSBmaWxl',
                      'name': 'myfile.txt',
                      'type': 'text/plain'}],
     'auto_html': None,
     'auto_text': None,
     'bcc_address': 'message.bcc_address@example.com',
     'from_email': 'message.from_email@example.com',
     'from_name': 'Example Name',
     'global_merge_vars': [{'content': 'merge1 content', 'name': 'merge1'}],
     'google_analytics_campaign': 'message.from_email@example.com',
     'google_analytics_domains': ['example.com'],
     'headers': {'Reply-To': 'message.reply@example.com'},
     'html': '<p>Example HTML content</p>',
     'images': [{'content': 'ZXhhbXBsZSBmaWxl',
                 'name': 'IMAGECID',
                 'type': 'image/png'}],
     'important': False,
     'inline_css': None,
     'merge': True,
     'merge_language': 'mailchimp',
     'merge_vars': [{'rcpt': 'recipient.email@example.com',
                     'vars': [{'content': 'merge2 content', 'name': 'merge2'}]}],
     'metadata': {'website': 'www.example.com'},
     'preserve_recipients': None,
     'recipient_metadata': [{'rcpt': 'recipient.email@example.com',
                             'values': {'user_id': 123456}}],
     'return_path_domain': None,
     'signing_domain': None,
     'subaccount': 'customer-123',
     'subject': 'example subject',
     'tags': ['password-resets'],
     'text': 'Example text content',
     'to': [{'email': 'recipient.email@example.com',
             'name': 'Recipient Name',
             'type': 'to'}],
     'track_clicks': None,
     'track_opens': None,
     'tracking_domain': None,
     'url_strip_qs': None,
     'view_content_link': None}
    result = mandrill_client.messages.send_template(template_name='example template_name', template_content=template_content, message=message, async=False, ip_pool='Main Pool', send_at='example send_at')
    '''
    [{'_id': 'abc123abc123abc123abc123abc123',
      'email': 'recipient.email@example.com',
      'reject_reason': 'hard-bounce',
      'status': 'sent'}]
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.UnknownSubaccountError'> - No subaccount exists with the id 'customer-123'
    raise

Parameters

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.

Example Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    tags = ['password-reset', 'welcome']
    senders = ['sender@example.com']
    api_keys = ['PmmzuovUZMPJsa73o3jjCw']
    result = mandrill_client.messages.search(query='email:gmail.com', date_from='2013-01-01', date_to='2013-01-02', tags=tags, senders=senders, api_keys=api_keys, limit=100)
    '''
    [{'_id': 'abc123abc123abc123abc123',
      'clicks': 42,
      'clicks_detail': [{'ip': '55.55.55.55',
                         'location': 'Georgia, US',
                         'ts': 1365190001,
                         'ua': 'Linux/Ubuntu/Chrome/Chrome 28.0.1500.53',
                         'url': 'http://www.example.com'}],
      'email': 'recipient.email@example.com',
      'metadata': {'user_id': '123', 'website': 'www.example.com'},
      'opens': 42,
      'opens_detail': [{'ip': '55.55.55.55',
                        'location': 'Georgia, US',
                        'ts': 1365190001,
                        'ua': 'Linux/Ubuntu/Chrome/Chrome 28.0.1500.53'}],
      'sender': 'sender@example.com',
      'state': 'sent',
      'subject': 'example subject',
      'tags': ['password-reset'],
      'template': 'example-template',
      'ts': 1365190000}]
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.ServiceUnavailableError'> - Service Temporarily Unavailable
    raise

Parameters
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

Example Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    tags = ['password-reset', 'welcome']
    senders = ['sender@example.com']
    result = mandrill_client.messages.search_time_series(query='email:gmail.com', date_from='2013-01-01', date_to='2013-01-02', tags=tags, senders=senders)
    '''
    [{'clicks': 42,
      'complaints': 42,
      'hard_bounces': 42,
      'opens': 42,
      'rejects': 42,
      'sent': 42,
      'soft_bounces': 42,
      'time': '2013-01-01 15:00:00',
      'unique_clicks': 42,
      'unique_opens': 42,
      'unsubs': 42}]
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.ServiceUnavailableError'> - Service Temporarily Unavailable
    raise

Parameters
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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    result = mandrill_client.messages.info(id='abc123abc123abc123abc123')
    '''
    {'_id': 'abc123abc123abc123abc123',
     'clicks': 42,
     'clicks_detail': [{'ip': '55.55.55.55',
                        'location': 'Georgia, US',
                        'ts': 1365190001,
                        'ua': 'Linux/Ubuntu/Chrome/Chrome 28.0.1500.53',
                        'url': 'http://www.example.com'}],
     'email': 'recipient.email@example.com',
     'metadata': {'user_id': '123', 'website': 'www.example.com'},
     'opens': 42,
     'opens_detail': [{'ip': '55.55.55.55',
                       'location': 'Georgia, US',
                       'ts': 1365190001,
                       'ua': 'Linux/Ubuntu/Chrome/Chrome 28.0.1500.53'}],
     'sender': 'sender@example.com',
     'smtp_events': [{'diag': '250 OK', 'ts': 1365190001, 'type': 'sent'}],
     'state': 'sent',
     'subject': 'example subject',
     'tags': ['password-reset'],
     'template': 'example-template',
     'ts': 1365190000}
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.UnknownMessageError'> - No message exists with the id 'McyuzyCS5M3bubeGPP-XVA'
    raise

Parameters
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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    result = mandrill_client.messages.content(id='abc123abc123abc123abc123')
    '''
    {'_id': 'abc123abc123abc123abc123',
     'attachments': [{'content': 'QSBzaW1wbGUgdGV4dCBzdHJpbmcgYXR0YWNobWVudA==',
                      'name': 'example.txt',
                      'type': 'text/plain'}],
     'from_email': 'sender@example.com',
     'from_name': 'Sender Name',
     'headers': {'Reply-To': 'replies@example.com'},
     'html': '<p>Some HTML content</p>',
     'subject': 'example subject',
     'tags': ['password-reset'],
     'text': 'Some text content',
     'to': {'email': 'recipient.email@example.com', 'name': 'Recipient Name'},
     'ts': 1365190000}
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.UnknownMessageError'> - No message exists with the id 'McyuzyCS5M3bubeGPP-XVA'
    raise

Parameters
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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    result = mandrill_client.messages.parse(raw_message='From: sender@example.com\nTo: recipient.email@example.com\nSubject: Some Subject\n\nSome content.')
    '''
    {'attachments': [{'binary': False,
                      'content': 'example non-binary content',
                      'name': 'example.txt',
                      'type': 'text/plain'}],
     'from_email': 'sender@example.com',
     'from_name': 'Sender Name',
     'headers': {'Reply-To': 'replies@example.com'},
     'html': '<p>Some HTML content</p>',
     'images': [{'content': 'ZXhhbXBsZSBmaWxl',
                 'name': 'IMAGEID',
                 'type': 'image/png'}],
     'subject': 'Some Subject',
     'text': 'Some text content',
     'to': [{'email': 'recipient.email@example.com', 'name': 'Recipient Name'}]}
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.InvalidKeyError'> - Invalid API key
    raise

Parameters
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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    to = ['recipient.email@example.com']
    result = mandrill_client.messages.send_raw(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=to, async=False, ip_pool='Main Pool', send_at='example send_at', return_path_domain=None)
    '''
    [{'_id': 'abc123abc123abc123abc123',
      'email': 'recipient.email@example.com',
      'reject_reason': 'hard-bounce',
      'status': 'sent'}]
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.UnknownSubaccountError'> - No subaccount exists with the id 'customer-123'
    raise

Parameters

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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    result = mandrill_client.messages.list_scheduled(to='test.recipient@example.com')
    '''
    [{'_id': 'I_dtFt2ZNPW5QD9-FaDU1A',
      'created_at': '2013-01-20 12:13:01',
      'from_email': 'sender@example.com',
      'send_at': '2021-01-05 12:42:01',
      'subject': 'This is a scheduled email',
      'to': 'test.recipient@example.com'}]
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.InvalidKeyError'> - Invalid API key
    raise

Parameters
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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    result = mandrill_client.messages.cancel_scheduled(id=None)
    '''
    {'_id': 'I_dtFt2ZNPW5QD9-FaDU1A',
     'created_at': '2013-01-20 12:13:01',
     'from_email': 'sender@example.com',
     'send_at': '2021-01-05 12:42:01',
     'subject': 'This is a scheduled email',
     'to': 'test.recipient@example.com'}
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.InvalidKeyError'> - Invalid API key
    raise

Parameters
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 Call


try:
    mandrill_client = mandrill.Mandrill('YOUR_API_KEY')
    result = mandrill_client.messages.reschedule(id='I_dtFt2ZNPW5QD9-FaDU1A', send_at='20120-06-01 08:15:01')
    '''
    {'_id': 'I_dtFt2ZNPW5QD9-FaDU1A',
     'created_at': '2013-01-20 12:13:01',
     'from_email': 'sender@example.com',
     'send_at': '2021-01-05 12:42:01',
     'subject': 'This is a scheduled email',
     'to': 'test.recipient@example.com'}
    '''

except mandrill.Error, e:
    # Mandrill errors are thrown as exceptions
    print 'A mandrill error occurred: %s - %s' % (e.__class__, e)
    # A mandrill error occurred: <class 'mandrill.UnknownMessageError'> - No message exists with the id 'McyuzyCS5M3bubeGPP-XVA'
    raise

Parameters
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.

Mandrill by Mailchimp

Messages Calls

/messages/send.json

Example Call

/messages/send-template.json

Example Call

/messages/search.json

Example Call

/messages/search-time-series.json

Example Call

/messages/info.json

Example Call

/messages/content.json

Example Call

/messages/parse.json

Example Call

/messages/send-raw.json

Example Call

/messages/list-scheduled.json

Example Call

/messages/cancel-scheduled.json

Example Call

/messages/reschedule.json

Example Call