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: * - headers struct optional extra headers to add to the message (currently only Reply-To and X-* headers are allowed)
21: * - important boolean whether or not this message is important, and should be delivered ahead of non-important messages
22: * - track_opens boolean whether or not to turn on open tracking for the message
23: * - track_clicks boolean whether or not to turn on click tracking for the message
24: * - auto_text boolean whether or not to automatically generate a text part for messages that are not given text
25: * - auto_html boolean whether or not to automatically generate an HTML part for messages that are not given HTML
26: * - 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
27: * - url_strip_qs boolean whether or not to strip the query string from URLs when aggregating tracked URL data
28: * - preserve_recipients boolean whether or not to expose all recipients in to "To" header for each email
29: * - bcc_address string an optional address to receive an exact copy of each recipient's email
30: * - tracking_domain string a custom domain to use for tracking opens and clicks instead of mandrillapp.com
31: * - signing_domain string a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
32: * - 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.
33: * - global_merge_vars array global merge variables to use for all recipients. You can override these per recipient.
34: * - global_merge_vars[] struct a single global merge variable
35: * - name string the global merge variable's name. Merge variable names are case-insensitive and may not start with _
36: * - content string the global merge variable's content
37: * - merge_vars array per-recipient merge variables, which override global merge variables with the same name.
38: * - merge_vars[] struct per-recipient merge variables
39: * - rcpt string the email address of the recipient that the merge variables should apply to
40: * - vars array the recipient's merge variables
41: * - vars[] struct a single merge variable
42: * - name string the merge variable's name. Merge variable names are case-insensitive and may not start with _
43: * - content string the merge variable's content
44: * - 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.
45: * - tags[] string a single tag - must not start with an underscore
46: * - 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.
47: * - 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.
48: * - 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.
49: * - recipient_metadata array Per-recipient metadata that will override the global values specified in the metadata parameter.
50: * - recipient_metadata[] struct metadata for a single recipient
51: * - rcpt string the email address of the recipient that the metadata is associated with
52: * - 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.
53: * - attachments array an array of supported attachments to add to the message
54: * - attachments[] struct a single supported attachment
55: * - type string the MIME type of the attachment
56: * - name string the file name of the attachment
57: * - content string the content of the attachment as a base64-encoded string
58: * - images array an array of embedded images to add to the message
59: * - images[] struct a single embedded image
60: * - type string the MIME type of the image - must start with "image/"
61: * - name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
62: * - content string the content of the image as a base64-encoded string
63: * @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.
64: * @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.
65: * @return array of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
66: * - return[] struct the sending results for a single recipient
67: * - email string the email address of the recipient
68: * - status string the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
69: * - reject_reason string the reason for the rejection if the recipient status is "rejected"
70: * - _id string the message's unique id
71: */
72: public function send($message, $async=false, $ip_pool=null) {
73: $_params = array("message" => $message, "async" => $async, "ip_pool" => $ip_pool);
74: return $this->master->call('messages/send', $_params);
75: }
76:
77: /**
78: * Send a new transactional message through Mandrill using a template
79: * @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.
80: * @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
81: * - template_content[] struct the injection of a single piece of content into a single editable region
82: * - name string the name of the mc:edit editable region to inject into
83: * - content string the content to inject
84: * @param struct $message the other information on the message to send - same as /messages/send, but without the html content
85: * - html string optional full HTML content to be sent if not in template
86: * - text string optional full text content to be sent
87: * - subject string the message subject
88: * - from_email string the sender email address.
89: * - from_name string optional from name to be used
90: * - to array an array of recipient information.
91: * - to[] struct a single recipient's information.
92: * - email string the email address of the recipient
93: * - name string the optional display name to use for the recipient
94: * - headers struct optional extra headers to add to the message (currently only Reply-To and X-* headers are allowed)
95: * - important boolean whether or not this message is important, and should be delivered ahead of non-important messages
96: * - track_opens boolean whether or not to turn on open tracking for the message
97: * - track_clicks boolean whether or not to turn on click tracking for the message
98: * - auto_text boolean whether or not to automatically generate a text part for messages that are not given text
99: * - auto_html boolean whether or not to automatically generate an HTML part for messages that are not given HTML
100: * - 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
101: * - url_strip_qs boolean whether or not to strip the query string from URLs when aggregating tracked URL data
102: * - preserve_recipients boolean whether or not to expose all recipients in to "To" header for each email
103: * - bcc_address string an optional address to receive an exact copy of each recipient's email
104: * - tracking_domain string a custom domain to use for tracking opens and clicks instead of mandrillapp.com
105: * - signing_domain string a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
106: * - 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.
107: * - global_merge_vars array global merge variables to use for all recipients. You can override these per recipient.
108: * - global_merge_vars[] struct a single global merge variable
109: * - name string the global merge variable's name. Merge variable names are case-insensitive and may not start with _
110: * - content string the global merge variable's content
111: * - merge_vars array per-recipient merge variables, which override global merge variables with the same name.
112: * - merge_vars[] struct per-recipient merge variables
113: * - rcpt string the email address of the recipient that the merge variables should apply to
114: * - vars array the recipient's merge variables
115: * - vars[] struct a single merge variable
116: * - name string the merge variable's name. Merge variable names are case-insensitive and may not start with _
117: * - content string the merge variable's content
118: * - 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.
119: * - tags[] string a single tag - must not start with an underscore
120: * - 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.
121: * - 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.
122: * - 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.
123: * - recipient_metadata array Per-recipient metadata that will override the global values specified in the metadata parameter.
124: * - recipient_metadata[] struct metadata for a single recipient
125: * - rcpt string the email address of the recipient that the metadata is associated with
126: * - 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.
127: * - attachments array an array of supported attachments to add to the message
128: * - attachments[] struct a single supported attachment
129: * - type string the MIME type of the attachment
130: * - name string the file name of the attachment
131: * - content string the content of the attachment as a base64-encoded string
132: * - images array an array of embedded images to add to the message
133: * - images[] struct a single embedded image
134: * - type string the MIME type of the image - must start with "image/"
135: * - name string the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
136: * - content string the content of the image as a base64-encoded string
137: * @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.
138: * @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.
139: * @return array of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
140: * - return[] struct the sending results for a single recipient
141: * - email string the email address of the recipient
142: * - status string the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
143: * - reject_reason string the reason for the rejection if the recipient status is "rejected"
144: * - _id string the message's unique id
145: */
146: public function sendTemplate($template_name, $template_content, $message, $async=false, $ip_pool=null) {
147: $_params = array("template_name" => $template_name, "template_content" => $template_content, "message" => $message, "async" => $async, "ip_pool" => $ip_pool);
148: return $this->master->call('messages/send-template', $_params);
149: }
150:
151: /**
152: * Search the content of recently sent messages and optionally narrow by date range, tags and senders
153: * @param string $query the search terms to find matching messages for
154: * @param string $date_from start date
155: * @param string $date_to end date
156: * @param array $tags an array of tag names to narrow the search to, will return messages that contain ANY of the tags
157: * @param array $senders an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
158: * @param integer $limit the maximum number of results to return, defaults to 100, 1000 is the maximum
159: * @return array of structs for each matching message
160: * - return[] struct the information for a single matching message
161: * - ts integer the Unix timestamp from when this message was sent
162: * - _id string the message's unique id
163: * - sender string the email address of the sender
164: * - subject string the message's subject link
165: * - email string the recipient email address
166: * - tags array list of tags on this message
167: * - tags[] string individual tag on this message
168: * - opens integer how many times has this message been opened
169: * - clicks integer how many times has a link been clicked in this message
170: * - state string sending status of this message: sent, bounced, rejected
171: * - metadata struct any custom metadata provided when the message was sent
172: */
173: public function search($query='*', $date_from=null, $date_to=null, $tags=null, $senders=null, $limit=100) {
174: $_params = array("query" => $query, "date_from" => $date_from, "date_to" => $date_to, "tags" => $tags, "senders" => $senders, "limit" => $limit);
175: return $this->master->call('messages/search', $_params);
176: }
177:
178: /**
179: * Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces
180: * @param string $raw_message the full MIME document of an email message
181: * @return struct the parsed message
182: * - subject string the subject of the message
183: * - from_email string the email address of the sender
184: * - from_name string the alias of the sender (if any)
185: * - to array an array of any recipients in the message
186: * - to[] struct the information on a single recipient
187: * - email string the email address of the recipient
188: * - name string the alias of the recipient (if any)
189: * - headers struct the key-value pairs of the MIME headers for the message's main document
190: * - text string the text part of the message, if any
191: * - html string the HTML part of the message, if any
192: * - attachments array an array of any attachments that can be found in the message
193: * - attachments[] struct information about an individual attachment
194: * - name string the file name of the attachment
195: * - type string the MIME type of the attachment
196: * - binary boolean if this is set to true, the attachment is not pure-text, and the content will be base64 encoded
197: * - content string the content of the attachment as a text string or a base64 encoded string based on the attachment type
198: * - images array an array of any embedded images that can be found in the message
199: * - images[] struct information about an individual image
200: * - name string the Content-ID of the embedded image
201: * - type string the MIME type of the image
202: * - content string the content of the image as a base64 encoded string
203: */
204: public function parse($raw_message) {
205: $_params = array("raw_message" => $raw_message);
206: return $this->master->call('messages/parse', $_params);
207: }
208:
209: /**
210: * Take a raw MIME document for a message, and send it exactly as if it were sent over the SMTP protocol
211: * @param string $raw_message the full MIME document of an email message
212: * @param string|null $from_email optionally define the sender address - otherwise we'll use the address found in the provided headers
213: * @param string|null $from_name optionally define the sender alias
214: * @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
215: * - to[] string the email address of the recipint
216: * @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.
217: * @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.
218: * @return array of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
219: * - return[] struct the sending results for a single recipient
220: * - email string the email address of the recipient
221: * - status string the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
222: * - reject_reason string the reason for the rejection if the recipient status is "rejected"
223: * - _id string the message's unique id
224: */
225: public function sendRaw($raw_message, $from_email=null, $from_name=null, $to=null, $async=false, $ip_pool=null) {
226: $_params = array("raw_message" => $raw_message, "from_email" => $from_email, "from_name" => $from_name, "to" => $to, "async" => $async, "ip_pool" => $ip_pool);
227: return $this->master->call('messages/send-raw', $_params);
228: }
229:
230: }
231:
232:
233: