Methods summary
public
|
|
public
array
|
#
send( struct $message, boolean $async = false, string $ip_pool = null, string $send_at = null )
Send a new transactional message through Mandrill
Send a new transactional message through Mandrill
Parameters
- $message
- 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. - 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 - 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 - 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 - 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 -
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 - 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 - 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
- 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
- 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
- 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.
Returns
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", or "rule" - _id string the message's unique id
|
public
array
|
#
sendTemplate( string $template_name, array $template_content, struct $message, boolean $async = false, string $ip_pool = null, string $send_at = null )
Send a new transactional message through Mandrill using a template
Send a new transactional message through Mandrill using a template
Parameters
- $template_name
- 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.
- $template_content
- 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 - content string
the content to inject
- $message
- 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. -
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 - 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 - 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 - 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 -
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 - 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 - 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
- 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
- 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
- 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.
Returns
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", or "rule" - _id string the message's unique id
|
public
array
|
#
search( string $query = '*', string $date_from = null, string $date_to = null, array $tags = null, array $senders = null, array $api_keys = null, integer $limit = 100 )
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.
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.
Parameters
- $query
- <a href="http://help.mandrill.com/entries/22211902">search terms</a> to find
matching messages
- $date_from
- start date
- $date_to
- end date
- $tags
- an array of tag names to narrow the search to, will return messages that contain
ANY of the tags
- $senders
- an array of sender addresses to narrow the search to, will return messages sent
by ANY of the senders
- $api_keys
- an array of API keys to narrow the search to, will return messages sent by ANY
of the keys
- $limit
- the maximum number of results to return, defaults to 100, 1000 is the maximum
Returns
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
|
public
array
|
#
searchTimeSeries( string $query = '*', string $date_from = null, string $date_to = null, array $tags = null, array $senders = null )
Search the content of recently sent messages and return the aggregated hourly
stats for matching messages
Search the content of recently sent messages and return the aggregated hourly
stats for matching messages
Parameters
- $query
- the search terms to find matching messages for
- $date_from
- start date
- $date_to
- end date
- $tags
- an array of tag names to narrow the search to, will return messages that contain
ANY of the tags
- $senders
- an array of sender addresses to narrow the search to, will return messages sent
by ANY of the senders
Returns
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
|
public
struct
|
#
info( string $id )
Get the information for a single recently sent message
Get the information for a single recently sent message
Parameters
- $id
- the unique id of the message to get - passed as the "_id" field in webhooks,
send calls, or search calls
Returns
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
|
public
struct
|
#
content( string $id )
Get the full content of a recently sent message
Get the full content of a recently sent message
Parameters
- $id
- the unique id of the message to get - passed as the "_id" field in webhooks,
send calls, or search calls
Returns
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
|
public
struct
|
#
parse( string $raw_message )
Parse the full MIME document for an email message, returning the content of
the message broken into its constituent pieces
Parse the full MIME document for an email message, returning the content of
the message broken into its constituent pieces
Parameters
- $raw_message
- the full MIME document of an email message
Returns
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
|
public
array
|
#
sendRaw( string $raw_message, string|null $from_email = null, string|null $from_name = null, array|null $to = null, boolean $async = false, string $ip_pool = null, string $send_at = null, string $return_path_domain = null )
Take a raw MIME document for a message, and send it exactly as if it were
sent through Mandrill's SMTP servers
Take a raw MIME document for a message, and send it exactly as if it were
sent through Mandrill's SMTP servers
Parameters
- $raw_message
- the full MIME document of an email message
- $from_email
- optionally define the sender address - otherwise we'll use the address found in
the provided headers
- $from_name
- optionally define the sender alias
- $to
- 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
- 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
- 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
- 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.
- $return_path_domain
- a custom domain to use for the messages's return-path
Returns
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", or "rule" - _id string the message's unique id
|
public
array
|
#
listScheduled( string $to = null )
Queries your scheduled emails.
Queries your scheduled emails.
Parameters
- $to
- an optional recipient address to restrict results to
Returns
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
|
public
struct
|
#
cancelScheduled( string $id )
Cancels a scheduled email.
Cancels a scheduled email.
Parameters
- $id
- a scheduled email id, as returned by any of the messages/send calls or
messages/list-scheduled
Returns
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
|
public
struct
|
#
reschedule( string $id, string $send_at )
Reschedules a scheduled email.
Reschedules a scheduled email.
Parameters
- $id
- a scheduled email id, as returned by any of the messages/send calls or
messages/list-scheduled
- $send_at
- 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
Returns
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
|