Working with the Mandrill mail service API

Mandrill is a powerful mail service from MailChimp. It is one of the most convenient to use and configure from a family of similar services for sending email notifications. This service is convenient to use not only to send some commercial letters, but also ordinary notifications from a personal site. Since emails sent from personal sites can get into spam, this will be another plus in favor of the decision to choose the services of this service.

For the Mandrill service to interact with the application, there is an API with a fairly wide range of capabilities, with the main ones we will have to meet. In addition, it is possible to use the basic (free account) that allows you to send up to 12,000 emails per month.

API usage

Since the implementation of interaction with the Mandrill API is supposed to be implemented in PHP, we take the library from here . You can use the installation via Composer or the standard installation (download, unpack and connect the necessary modules). If you chose the second installation option, then you need to find the “src” directory in the downloaded archive, which contains the files and directories of the required library.
')
In order to be able to use the API, you must obtain an API key (meaning that you are already registered). Go to your account and on the left in the menu click on the “Settings” item and in the “API Keys” section we will be able to see your key:



Next, you need to create a subaccount. To do this, in the left-side menu, click on the “Outbound” item and after opening the corresponding settings section, click the “Create a Subaccount” button:



To send a letter, you can use a previously created template that should be available in your account, or you can limit yourself to sending a regular text message. It is also possible to design letters in HTML format. To send a letter, there are the following methods of the Mandrill_Messages class:

• array send (message [, async = false [, ip_pool = null [, send_at = null]]]) - as a message parameter, you must pass the data structure filled in as an array, as shown in Table. 1 . Parameter async - sets the background batch sending messages. As the ip_pool parameter, you must specify the name of the selected pool of ip addresses, as can be seen from the description of the function's prototype, this parameter is not mandatory. And as the last parameter to send_at, you can specify the time in the UTC format timestamp YYYY-MM-DD HH: MM: SS for the scheduled message sending. But this will require a paid account with a positive balance;
• array sendTemplate (template_name, template_content, message [, async = false [, ip_pool = null [, send_at = null]]]) - this method differs from the previous one by the presence of two additional parameters. The first parameter, template_name, is the name of an existing template. And the second parameter template_content is an array of dynamic content elements, the data structure of which is described in Table. 2 More details can be found here .

Table 1 . Description of data structure fields for sending email

Parameter	Description
html string	Text with HTML markup content.
text string	Text of the letter.
subject string	Topic of the letter.
from_email string	Email sender.
from_name string	Sender name.
to array	An array of “to” elements containing the sender data.
global_merge_vars array	An array of global_merge_vars elements containing global data about template labels.
merge_vars array	An array of merge_vars elements containing data on template labels.
subaccount string	The unique identifier of the subaccount.
attachments array	Array of attachments added to the letter.
images array	Array of images added to the letter.
The structure of the parameter array to
email string	Email recipient.
name string	Name of the addressee.
type string	Header type. The default is “to”. Possible options (to, cc, bcc).
The structure of the array parameter global_merge_vars
name string	Variable name, case sensitive. The variable name cannot begin with the “_” character.
content string	Variable value
The structure of the parameter array merge_vars
rcpt string	Email address of the recipient to which the local wildcards of the template will be applied.
vars array	An array of “vars” elements containing local data about template labels. The structure of the “vars” array parameter is identical to the structure of the “global_merge_vars” array parameter.
The parameter structure of the attachments array
type string	MIME type of attachments.
name string	File name.
content string	The contents of the file must be in base64 encoding.
The parameter structure of the images array.
type string	MIME file type - must be an image.
name string	File name.
content string	The contents of the file must be in base64 encoding.

Table 2 . The structure of the array element used in the template_content parameter

Parameter	Description
name string	The name of the label.
content string	The content of the label.

The send () method allows you to text send a letter, and the second method provides the ability to send letters using pre-created templates. Both methods return an array with the data structure presented in Table. 3

Table 3 . Response structure, for each addressee

Parameter	Description
email string	Email recipient.
status string	Sending status: sent, queued, scheduled, rejected or not possible to send.
reject_reason string	The reason for the failure to deliver the letter. Maybe one of the following options: rejected, hard-bounce, soft-bounce, spam, unsub, custom, invalid-sender, invalid, test-mode-limit, rule
_id string	The unique identifier of the message sent.

In order not to be distracted later, we will create a template for the future immediately. To do this, in the left-side menu that is already familiar to us, click on the “Outbound” item and after moving to the appropriate section, click the “Create a Template” button:



Here we will be asked to enter the name of the template. After entering one, press the “Start Coding” button:



And at the final stage, we need to fill in the proposed fields. Then in the right field you need to write the code for the future of our wildcard pattern. Note that the template editor must be in “HTML” mode. After filling in all the fields we need, click the “Publish” button:



Now that everything is set up, you can send a letter. Source code for sending a letter:

//   Mandrill require_once ('Mandrill.php'); $mail = new Mandrill('API key'); /*    */ $tpl_con = array( array( 'name' => 'my-label', 'content' => '<h2> </h2>' ) ); $data = array( 'html' => 'It is html text', 'text' => 'It is simple text', 'subject' => 'Hi friend', 'from_email' => 'friend@example.com', 'from_name' => 'Michael', 'to' => array( array( 'email' => 'example@gmail.com', 'name' => 'Lucas', 'type' => 'to' ) ), 'global_merge_vars' => array( array( 'name' => 'NAME', 'content' => 'Lucas' ) ), 'merge_vars' => array( array( 'rcpt' => 'example@gmail.com', 'vars' => array( array( 'name' => 'NAME', 'content' => 'Lucas' ) ) ) ), 'attachments' => array( array( 'type' => 'application/pdf', 'name' => 'test.pdf', 'content' => base64_encode(file_get_contents('test.pdf')) ) ), 'images' => array( array( 'type' => 'image/png', 'name' => 'Smiley.png', 'content' => base64_encode(file_get_contents('Smiley.png')) ) ), 'subaccount' => 'cust-123' ); try { /*    */ $result = $mail->messages->send($data); print_r($result); /*      */ $result = $mail->messages->sendTemplate('example', $tpl_con, $data); print_r($result); } catch(Mandrill_Error $error) { echo 'Error: ' . get_class($error) . ' - ' . $error->getMessage(); } 

The results of the two methods are presented below. The bottom image shows the result of applying the template.



We sent the same email using both methods available to us. In order to be able to see the differences. As an example, an image and a PDF document were attached to the letter.
Work with dynamic content and templates was also demonstrated. The difference in the use of the template from the dynamic content is that the label is specified for the template.

This label will be replaced in the future by its contents. And for dynamic content in the HTML tag indicates the following attribute.

where, section-name is a unique identifier, meaning that the data of the specified identifier will be inserted into the HTML tag containing it. It is also worth considering that the template elements specified in the global_merge_vars field (see Table 1 ) will be replaced with the corresponding elements specified in the vars field of the merge_vars structure for specified email addresses in the rcpt field of the merge_vars structure ".

Consider the following example:

 'to' => array( array( 'email' => 'example_1@gmail.com', 'name' => 'Lucas 2', 'type' => 'to' ), array( 'email' => 'example_2@gmail.com', 'name' => 'Lucas 1', 'type' => 'to' ) ), 'global_merge_vars' => array( array( 'name' => 'NAME', 'content' => 'Lucas' ) ), 'merge_vars' => array( array( 'rcpt' => 'example_1@gmail.com', 'vars' => array( array( 'name' => 'NAME', 'content' => 'Alex' ) ) ) ) 

Here the label will be redefined only for the recipient with the address “example_1@gmail.com”. Accordingly, the label in the template with the name “ NAME ” will be replaced with the name “ Alex ”, for the remaining recipients the content of the label will remain “ Lucas ”.
When using both methods to send letters, the following factors should be considered:

• When using the send () method:
  
  • If the “html” field is specified in the data structure (see Table 1 ) and it contains some data, then the “text” field will be covered by it.
  
  
• When using the sendTemplate () method:
  
  • If the template editor in the template editor (see above) has the format “HTML”, then neither of the two fields: “html” and “text” will not be able to block the text of the template;
  • If in the template editor, the template has the format “Text”, then for its automatic substitution in the letter template when sending, it is prohibited to specify the following fields in the data structure: “html” and “text”. It is possible to specify more correctly, but they should not contain any data, otherwise the data specified in one of the two fields will go in the order of priority (html, text);
  • If the “subject” field is not filled in the template, the priority will go to the field of the same name (if any) in the data structure (see Table 1 ).
  
  

The list of possible errors is contained in the table. four.

Table 4 . The list of possible errors in case of a failed letter sending

Invalid_Key	Invalid API key.
Unknown_Message	Message ID does not exist.
Validation error	Parameters passed during the call are incorrect.
GeneralError	An error occurred during the request.