# File Mandrill/Messages.php

      1: <?php
      2:
      3: class Mandrill_Messages {
      4:     public function __construct(Mandrill $master) {
      5:         $this->master = $master;
      6:     }
      7:
      8:     /**
      9:      * Send a new transactional message through Mandrill
     10:      * @param struct $message the information on the message to send
     11:      *     - html string the full HTML content to be sent
     12:      *     - text string optional full text content to be sent
     13:      *     - subject string the message subject
     14:      *     - from_email string the sender email address.
     15:      *     - from_name string optional from name to be used
     16:      *     - to array an array of recipient information.
     17:      *         - to[] struct a single recipient's information.
     18:      *             - email string the email address of the recipient
     19:      *             - name string the optional display name to use for the recipient
     20:      *             - type string the header type to use for the recipient, defaults to "to" if not provided
     21:      *     - headers struct optional extra headers to add to the message (most headers are allowed)
     22:      *     - important boolean whether or not this message is important, and should be delivered ahead of non-important messages
     23:      *     - track_opens boolean whether or not to turn on open tracking for the message
     24:      *     - track_clicks boolean whether or not to turn on click tracking for the message
     25:      *     - auto_text boolean whether or not to automatically generate a text part for messages that are not given text
     26:      *     - auto_html boolean whether or not to automatically generate an HTML part for messages that are not given HTML
     27:      *     - 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
     28:      *     - url_strip_qs boolean whether or not to strip the query string from URLs when aggregating tracked URL data
     29:      *     - preserve_recipients boolean whether or not to expose all recipients in to "To" header for each email
     30:      *     - view_content_link boolean set to false to remove content logging for sensitive emails
     31:      *     - bcc_address string an optional address to receive an exact copy of each recipient's email
     32:      *     - tracking_domain string a custom domain to use for tracking opens and clicks instead of mandrillapp.com
     33:      *     - signing_domain string a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
     34:      *     - return_path_domain string a custom domain to use for the messages's return-path
     35:      *     - 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.
     36:      *     - global_merge_vars array global merge variables to use for all recipients. You can override these per recipient.
     37:      *         - global_merge_vars[] struct a single global merge variable
     38:      *             - name string the global merge variable's name. Merge variable names are case-insensitive and may not start with _
     39:      *             - content string the global merge variable's content
     40:      *     - merge_vars array per-recipient merge variables, which override global merge variables with the same name.
     41:      *         - merge_vars[] struct per-recipient merge variables
     42:      *             - rcpt string the email address of the recipient that the merge variables should apply to
     43:      *             - vars array the recipient's merge variables
     44:      *                 - vars[] struct a single merge variable
     45:      *                     - name string the merge variable's name. Merge variable names are case-insensitive and may not start with _
     46:      *                     - content string the merge variable's content
     47:      *     - 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.
     48:      *         - tags[] string a single tag - must not start with an underscore
     49:      *     - subaccount string the unique id of a subaccount for this message - must already exist or will fail with an error
     50:      *     - 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.
     51:      *     - 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.
     52:      *     - 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.
     53:      *     - recipient_metadata array Per-recipient metadata that will override the global values specified in the metadata parameter.
     54:      *         - recipient_metadata[] struct metadata for a single recipient
     55:      *             - rcpt string the email address of the recipient that the metadata is associated with
     56:      *             - 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.
     57:      *     - attachments array an array of supported attachments to add to the message
     58:      *         - attachments[] struct a single supported attachment
     59:      *             - type string the MIME type of the attachment
     60:      *             - name string the file name of the attachment
     61:      *             - content string the content of the attachment as a base64-encoded string
     62:      *     - images array an array of embedded images to add to the message
     63:      *         - images[] struct a single embedded image
     64:      *             - type string the MIME type of the image - must start with "image/"
     65:      *             - name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
     66:      *             - content string the content of the image as a base64-encoded string
     67:      * @param boolean $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.
     68:      * @param string $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.
     69:      * @param string $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.
     70:      * @return array of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
     71:      *     - return[] struct the sending results for a single recipient
     72:      *         - email string the email address of the recipient
     73:      *         - status string the sending status of the recipient - either "sent", "queued", "scheduled", "rejected", or "invalid"
     74:      *         - reject_reason string the reason for the rejection if the recipient status is "rejected"
     75:      *         - _id string the message's unique id
     76:      */
     77:     public function send($message, $async=false, $ip_pool=null, $send_at=null) {
     78:         $_params = array("message" => $message, "async" => $async, "ip_pool" => $ip_pool, "send_at" => $send_at);
     79:         return $this->master->call('messages/send', $_params);
     80:     }
     81:
     82:     /**
     83:      * Send a new transactional message through Mandrill using a template
     84:      * @param string $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.
     85:      * @param array $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
     86:      *     - template_content[] struct the injection of a single piece of content into a single editable region
     87:      *         - name string the name of the mc:edit editable region to inject into
     88:      *         - content string the content to inject
     89:      * @param struct $message the other information on the message to send - same as /messages/send, but without the html content
     90:      *     - html string optional full HTML content to be sent if not in template
     91:      *     - text string optional full text content to be sent
     92:      *     - subject string the message subject
     93:      *     - from_email string the sender email address.
     94:      *     - from_name string optional from name to be used
     95:      *     - to array an array of recipient information.
     96:      *         - to[] struct a single recipient's information.
     97:      *             - email string the email address of the recipient
     98:      *             - name string the optional display name to use for the recipient
     99:      *             - type string the header type to use for the recipient, defaults to "to" if not provided
    100:      *     - headers struct optional extra headers to add to the message (most headers are allowed)
    101:      *     - important boolean whether or not this message is important, and should be delivered ahead of non-important messages
    102:      *     - track_opens boolean whether or not to turn on open tracking for the message
    103:      *     - track_clicks boolean whether or not to turn on click tracking for the message
    104:      *     - auto_text boolean whether or not to automatically generate a text part for messages that are not given text
    105:      *     - auto_html boolean whether or not to automatically generate an HTML part for messages that are not given HTML
    106:      *     - 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
    107:      *     - url_strip_qs boolean whether or not to strip the query string from URLs when aggregating tracked URL data
    108:      *     - preserve_recipients boolean whether or not to expose all recipients in to "To" header for each email
    109:      *     - view_content_link boolean set to false to remove content logging for sensitive emails
    110:      *     - bcc_address string an optional address to receive an exact copy of each recipient's email
    111:      *     - tracking_domain string a custom domain to use for tracking opens and clicks instead of mandrillapp.com
    112:      *     - signing_domain string a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
    113:      *     - return_path_domain string a custom domain to use for the messages's return-path
    114:      *     - 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.
    115:      *     - global_merge_vars array global merge variables to use for all recipients. You can override these per recipient.
    116:      *         - global_merge_vars[] struct a single global merge variable
    117:      *             - name string the global merge variable's name. Merge variable names are case-insensitive and may not start with _
    118:      *             - content string the global merge variable's content
    119:      *     - merge_vars array per-recipient merge variables, which override global merge variables with the same name.
    120:      *         - merge_vars[] struct per-recipient merge variables
    121:      *             - rcpt string the email address of the recipient that the merge variables should apply to
    122:      *             - vars array the recipient's merge variables
    123:      *                 - vars[] struct a single merge variable
    124:      *                     - name string the merge variable's name. Merge variable names are case-insensitive and may not start with _
    125:      *                     - content string the merge variable's content
    126:      *     - 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.
    127:      *         - tags[] string a single tag - must not start with an underscore
    128:      *     - subaccount string the unique id of a subaccount for this message - must already exist or will fail with an error
    129:      *     - 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.
    130:      *     - 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.
    131:      *     - 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.
    132:      *     - recipient_metadata array Per-recipient metadata that will override the global values specified in the metadata parameter.
    133:      *         - recipient_metadata[] struct metadata for a single recipient
    134:      *             - rcpt string the email address of the recipient that the metadata is associated with
    135:      *             - 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.
    136:      *     - attachments array an array of supported attachments to add to the message
    137:      *         - attachments[] struct a single supported attachment
    138:      *             - type string the MIME type of the attachment
    139:      *             - name string the file name of the attachment
    140:      *             - content string the content of the attachment as a base64-encoded string
    141:      *     - images array an array of embedded images to add to the message
    142:      *         - images[] struct a single embedded image
    143:      *             - type string the MIME type of the image - must start with "image/"
    144:      *             - name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
    145:      *             - content string the content of the image as a base64-encoded string
    146:      * @param boolean $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.
    147:      * @param string $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.
    148:      * @param string $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.
    149:      * @return array of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", "scheduled", or "rejected"
    150:      *     - return[] struct the sending results for a single recipient
    151:      *         - email string the email address of the recipient
    152:      *         - status string the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
    153:      *         - reject_reason string the reason for the rejection if the recipient status is "rejected"
    154:      *         - _id string the message's unique id
    155:      */
    156:     public function sendTemplate($template_name, $template_content, $message, $async=false, $ip_pool=null, $send_at=null) {
    157:         $_params = array("template_name" => $template_name, "template_content" => $template_content, "message" => $message, "async" => $async, "ip_pool" => $ip_pool, "send_at" => $send_at);
    158:         return $this->master->call('messages/send-template', $_params);
    159:     }
    160:
    161:     /**
    162:      * Search the content of recently sent messages and optionally narrow by date range, tags and senders
    163:      * @param string $query the search terms to find matching messages for
    164:      * @param string $date_from start date
    165:      * @param string $date_to end date
    166:      * @param array $tags an array of tag names to narrow the search to, will return messages that contain ANY of the tags
    167:      * @param array $senders an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
    168:      * @param array $api_keys an array of API keys to narrow the search to, will return messages sent by ANY of the keys
    169:      * @param integer $limit the maximum number of results to return, defaults to 100, 1000 is the maximum
    170:      * @return array of structs for each matching message
    171:      *     - return[] struct the information for a single matching message
    172:      *         - ts integer the Unix timestamp from when this message was sent
    173:      *         - _id string the message's unique id
    174:      *         - sender string the email address of the sender
    175:      *         - template string the unique name of the template used, if any
    176:      *         - subject string the message's subject line
    177:      *         - email string the recipient email address
    178:      *         - tags array list of tags on this message
    179:      *             - tags[] string individual tag on this message
    180:      *         - opens integer how many times has this message been opened
    181:      *         - opens_detail array list of individual opens for the message
    182:      *             - opens_detail[] struct information on an individual open
    183:      *                 - ts integer the unix timestamp from when the message was opened
    184:      *                 - ip string the IP address that generated the open
    185:      *                 - location string the approximate region and country that the opening IP is located
    186:      *                 - ua string the email client or browser data of the open
    187:      *         - clicks integer how many times has a link been clicked in this message
    188:      *         - clicks_detail array list of individual clicks for the message
    189:      *             - clicks_detail[] struct information on an individual click
    190:      *                 - ts integer the unix timestamp from when the message was clicked
    191:      *                 - url string the URL that was clicked on
    192:      *                 - ip string the IP address that generated the click
    193:      *                 - location string the approximate region and country that the clicking IP is located
    194:      *                 - ua string the email client or browser data of the click
    195:      *         - state string sending status of this message: sent, bounced, rejected
    196:      *         - metadata struct any custom metadata provided when the message was sent
    197:      *     - smtp_events array a log of up to 3 smtp events for the message
    198:      *         - smtp_events[] struct information about a specific smtp event
    199:      *             - ts integer the Unix timestamp when the event occured
    200:      *             - type string the message's state as a result of this event
    201:      *             - diag string the SMTP response from the recipient's server
    202:      */
    203:     public function search($query='*', $date_from=null, $date_to=null, $tags=null, $senders=null, $api_keys=null, $limit=100) {
    204:         $_params = array("query" => $query, "date_from" => $date_from, "date_to" => $date_to, "tags" => $tags, "senders" => $senders, "api_keys" => $api_keys, "limit" => $limit);
    205:         return $this->master->call('messages/search', $_params);
    206:     }
    207:
    208:     /**
    209:      * Search the content of recently sent messages and return the aggregated hourly stats for matching messages
    210:      * @param string $query the search terms to find matching messages for
    211:      * @param string $date_from start date
    212:      * @param string $date_to end date
    213:      * @param array $tags an array of tag names to narrow the search to, will return messages that contain ANY of the tags
    214:      * @param array $senders an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
    215:      * @return array the array of history information
    216:      *     - return[] struct the stats for a single hour
    217:      *         - time string the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
    218:      *         - sent integer the number of emails that were sent during the hour
    219:      *         - hard_bounces integer the number of emails that hard bounced during the hour
    220:      *         - soft_bounces integer the number of emails that soft bounced during the hour
    221:      *         - rejects integer the number of emails that were rejected during the hour
    222:      *         - complaints integer the number of spam complaints received during the hour
    223:      *         - unsubs integer the number of unsubscribes received during the hour
    224:      *         - opens integer the number of emails opened during the hour
    225:      *         - unique_opens integer the number of unique opens generated by messages sent during the hour
    226:      *         - clicks integer the number of tracked URLs clicked during the hour
    227:      *         - unique_clicks integer the number of unique clicks generated by messages sent during the hour
    228:      */
    229:     public function searchTimeSeries($query='*', $date_from=null, $date_to=null, $tags=null, $senders=null) {
    230:         $_params = array("query" => $query, "date_from" => $date_from, "date_to" => $date_to, "tags" => $tags, "senders" => $senders);
    231:         return $this->master->call('messages/search-time-series', $_params);
    232:     }
    233:
    234:     /**
    235:      * Get the information for a single recently sent message
    236:      * @param string $id the unique id of the message to get - passed as the "_id" field in webhooks, send calls, or search calls
    237:      * @return struct the information for the message
    238:      *     - ts integer the Unix timestamp from when this message was sent
    239:      *     - _id string the message's unique id
    240:      *     - sender string the email address of the sender
    241:      *     - template string the unique name of the template used, if any
    242:      *     - subject string the message's subject line
    243:      *     - email string the recipient email address
    244:      *     - tags array list of tags on this message
    245:      *         - tags[] string individual tag on this message
    246:      *     - opens integer how many times has this message been opened
    247:      *     - opens_detail array list of individual opens for the message
    248:      *         - opens_detail[] struct information on an individual open
    249:      *             - ts integer the unix timestamp from when the message was opened
    250:      *             - ip string the IP address that generated the open
    251:      *             - location string the approximate region and country that the opening IP is located
    252:      *             - ua string the email client or browser data of the open
    253:      *     - clicks integer how many times has a link been clicked in this message
    254:      *     - clicks_detail array list of individual clicks for the message
    255:      *         - clicks_detail[] struct information on an individual click
    256:      *             - ts integer the unix timestamp from when the message was clicked
    257:      *             - url string the URL that was clicked on
    258:      *             - ip string the IP address that generated the click
    259:      *             - location string the approximate region and country that the clicking IP is located
    260:      *             - ua string the email client or browser data of the click
    261:      *     - state string sending status of this message: sent, bounced, rejected
    262:      *     - metadata struct any custom metadata provided when the message was sent
    263:      *     - smtp_events array a log of up to 3 smtp events for the message
    264:      *         - smtp_events[] struct information about a specific smtp event
    265:      *             - ts integer the Unix timestamp when the event occured
    266:      *             - type string the message's state as a result of this event
    267:      *             - diag string the SMTP response from the recipient's server
    268:      */
    269:     public function info($id) {
    270:         $_params = array("id" => $id);
    271:         return $this->master->call('messages/info', $_params);
    272:     }
    273:
    274:     /**
    275:      * Get the full content of a recently sent message
    276:      * @param string $id the unique id of the message to get - passed as the "_id" field in webhooks, send calls, or search calls
    277:      * @return struct the content of the message
    278:      *     - ts integer the Unix timestamp from when this message was sent
    279:      *     - _id string the message's unique id
    280:      *     - from_email string the email address of the sender
    281:      *     - from_name string the alias of the sender (if any)
    282:      *     - subject string the message's subject line
    283:      *     - to struct the message recipient's information
    284:      *         - email string the email address of the recipient
    285:      *         - name string the alias of the recipient (if any)
    286:      *     - tags array list of tags on this message
    287:      *         - tags[] string individual tag on this message
    288:      *     - headers struct the key-value pairs of the custom MIME headers for the message's main document
    289:      *     - text string the text part of the message, if any
    290:      *     - html string the HTML part of the message, if any
    291:      *     - attachments array an array of any attachments that can be found in the message
    292:      *         - attachments[] struct information about an individual attachment
    293:      *             - name string the file name of the attachment
    294:      *             - type string the MIME type of the attachment
    295:      *             - content string the content of the attachment as a base64 encoded string
    296:      */
    297:     public function content($id) {
    298:         $_params = array("id" => $id);
    299:         return $this->master->call('messages/content', $_params);
    300:     }
    301:
    302:     /**
    303:      * Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces
    304:      * @param string $raw_message the full MIME document of an email message
    305:      * @return struct the parsed message
    306:      *     - subject string the subject of the message
    307:      *     - from_email string the email address of the sender
    308:      *     - from_name string the alias of the sender (if any)
    309:      *     - to array an array of any recipients in the message
    310:      *         - to[] struct the information on a single recipient
    311:      *             - email string the email address of the recipient
    312:      *             - name string the alias of the recipient (if any)
    313:      *     - headers struct the key-value pairs of the MIME headers for the message's main document
    314:      *     - text string the text part of the message, if any
    315:      *     - html string the HTML part of the message, if any
    316:      *     - attachments array an array of any attachments that can be found in the message
    317:      *         - attachments[] struct information about an individual attachment
    318:      *             - name string the file name of the attachment
    319:      *             - type string the MIME type of the attachment
    320:      *             - binary boolean if this is set to true, the attachment is not pure-text, and the content will be base64 encoded
    321:      *             - content string the content of the attachment as a text string or a base64 encoded string based on the attachment type
    322:      *     - images array an array of any embedded images that can be found in the message
    323:      *         - images[] struct information about an individual image
    324:      *             - name string the Content-ID of the embedded image
    325:      *             - type string the MIME type of the image
    326:      *             - content string the content of the image as a base64 encoded string
    327:      */
    328:     public function parse($raw_message) {
    329:         $_params = array("raw_message" => $raw_message);
    330:         return $this->master->call('messages/parse', $_params);
    331:     }
    332:
    333:     /**
    334:      * Take a raw MIME document for a message, and send it exactly as if it were sent through Mandrill's SMTP servers
    335:      * @param string $raw_message the full MIME document of an email message
    336:      * @param string|null $from_email optionally define the sender address - otherwise we'll use the address found in the provided headers
    337:      * @param string|null $from_name optionally define the sender alias
    338:      * @param array|null $to optionally define the recipients to receive the message - otherwise we'll use the To, Cc, and Bcc headers provided in the document
    339:      *     - to[] string the email address of the recipient
    340:      * @param boolean $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.
    341:      * @param string $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.
    342:      * @param string $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.
    343:      * @param string $return_path_domain a custom domain to use for the messages's return-path
    344:      * @return array of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
    345:      *     - return[] struct the sending results for a single recipient
    346:      *         - email string the email address of the recipient
    347:      *         - status string the sending status of the recipient - either "sent", "queued", "scheduled", "rejected", or "invalid"
    348:      *         - reject_reason string the reason for the rejection if the recipient status is "rejected"
    349:      *         - _id string the message's unique id
    350:      */
    351:     public function sendRaw($raw_message, $from_email=null, $from_name=null, $to=null, $async=false, $ip_pool=null, $send_at=null, $return_path_domain=null) {
    352:         $_params = array("raw_message" => $raw_message, "from_email" => $from_email, "from_name" => $from_name, "to" => $to, "async" => $async, "ip_pool" => $ip_pool, "send_at" => $send_at, "return_path_domain" => $return_path_domain);
    353:         return $this->master->call('messages/send-raw', $_params);
    354:     }
    355:
    356:     /**
    357:      * Queries your scheduled emails by sender or recipient, or both.
    358:      * @param string $to an optional recipient address to restrict results to
    359:      * @return array a list of up to 1000 scheduled emails
    360:      *     - return[] struct a scheduled email
    361:      *         - _id string the scheduled message id
    362:      *         - created_at string the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
    363:      *         - send_at string the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
    364:      *         - from_email string the email's sender address
    365:      *         - to string the email's recipient
    366:      *         - subject string the email's subject
    367:      */
    368:     public function listScheduled($to=null) {
    369:         $_params = array("to" => $to);
    370:         return $this->master->call('messages/list-scheduled', $_params);
    371:     }
    372:
    373:     /**
    374:      * Cancels a scheduled email.
    375:      * @param string $id a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled
    376:      * @return struct information about the scheduled email that was cancelled.
    377:      *     - _id string the scheduled message id
    378:      *     - created_at string the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
    379:      *     - send_at string the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
    380:      *     - from_email string the email's sender address
    381:      *     - to string the email's recipient
    382:      *     - subject string the email's subject
    383:      */
    384:     public function cancelScheduled($id) {
    385:         $_params = array("id" => $id);
    386:         return $this->master->call('messages/cancel-scheduled', $_params);
    387:     }
    388:
    389:     /**
    390:      * Reschedules a scheduled email.
    391:      * @param string $id a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled
    392:      * @param string $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
    393:      * @return struct information about the scheduled email that was rescheduled.
    394:      *     - _id string the scheduled message id
    395:      *     - created_at string the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
    396:      *     - send_at string the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
    397:      *     - from_email string the email's sender address
    398:      *     - to string the email's recipient
    399:      *     - subject string the email's subject
    400:      */
    401:     public function reschedule($id, $send_at) {
    402:         $_params = array("id" => $id, "send_at" => $send_at);
    403:         return $this->master->call('messages/reschedule', $_params);
    404:     }
    405:
    406: }
    407:
    408:
    409: