Работа с API почтового сервиса Mandrill

Mandrill это мощный почтовый сервис от MailChimp. Он является одним из самых удобных в использовании и настройке из семейства однотипных сервисов для отправки почтовых уведомлений. Этот сервис удобно использовать не только для рассылки неких писем коммерческого характера, но и обычных уведомлений с личного сайта. Так как электронные письма, отправляемые с личных сайтов, могут попадать в спам, то это будет еще одним плюсом в пользу решения о выборе услуг данного сервиса.
Для взаимодействия сервиса Mandrill с приложением, существует API с довольно широким спектром возможностей, с основными из них нам и предстоит, познакомиться. К тому же имеется возможность использования базового (бесплатного аккаунта) позволяющего производить рассылку до 12000 писем в месяц.

Использование API

Поскольку осуществление взаимодействия с API Mandrill предполагается реализовывать на PHP, то саму библиотеку берем отсюда. Можно воспользоваться установкой через Composer или стандартной установкой (скачиваем, распаковываем и подключаем необходимые модули). Если вы выбрали второй вариант установки, то вам необходимо найти в скачанном архиве каталог “src”, в нем то и содержатся файлы и каталоги необходимой библиотеки.
Для того чтобы иметь возможность использования API, необходимо получить API ключ (имеется ввиду, что вы уже зарегистрированы). Заходим в аккаунт и слева в меню кликаем по пункту “Settings” и в разделе “API Keys” сможем увидеть свой ключ:

Далее потребуется создать субаккаунт. Для этого опять же в левостороннем меню кликаем по пункту “Outbound” и после открытия соответствующего раздела настроек, нажимаем кнопку “Create a Subaccount”:

Для отправки письма можно воспользоваться заранее созданным шаблоном, который должен быть доступен в вашем аккаунте, или же ограничиться отправкой обычного текстового сообщения. Также имеется возможность оформления письма в формате HTML. Для отправки письма, существуют следующие методы класса Mandrill_Messages:

• array send(message [, async = false [, ip_pool = null [, send_at = null]]]) – в качестве параметра message требуется передать заполненную в виде массива структуру данных, приводимую в табл. 1. Параметр async – устанавливает фоновую пакетную отправку сообщений. В качестве параметра ip_pool требуется указывать имя выделенного пула ip адресов, как видно из описания прототипа функции этот параметр не является обязательным. И в качестве последнего параметра send_at можно указать время в формате UTC timestamp YYYY-MM-DD HH:MM:SS для запланированной отправки письма. Но для этого потребуется платный аккаунт с положительным балансом;
• array sendTemplate(template_name, template_content, message [, async = false [, ip_pool = null [, send_at = null]]]) – данный метод отличается от предыдущего наличием двух дополнительных параметров. В первом параметре template_name указывается имя существующего шаблона. А второй параметр template_content является массивом элементов динамического контента, структура данных которых описана в табл. 2. Подробнее можно ознакомиться здесь.

Таблица 1. Описание полей структуры данных для отправки письма

Таблица 2. Структура элемента массива использующегося в параметре template_content

Метод send() позволяет произвести текстовую отправку письма, а второй метод предоставляет возможность производить отправку писем с использованием, заранее созданных шаблонов. Оба метода возвращают массив со структурой данных представленной в табл. 3.

Таблица 3. Структура ответа, для каждого адресата

Чтобы потом не отвлекаться, создадим на будущее сразу и шаблон. Для этого в уже знакомом нам левостороннем меню кликаем по пункту “Outbound” и после перехода в соответствующий раздел, нажимаем кнопку “Create a Template”:

Здесь нам будет предложено ввести имя шаблона. После ввода такового, нажимаем кнопку “Start Coding”:

И уже на завершающем этапе нам необходимо заполнить предлагаемые поля. Затем в правом поле нужно написать код для будущего нашего подстановочного шаблона. Обратите внимание на то, что редактор шаблона должен находиться в режиме “HTML”. После заполнения всех необходимых нам полей, нажимаем кнопку “Publish”:

Теперь, когда уже все настроено, можно производить отправку письма. Исходный код отправки письма:

// Подключение библиотеки 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(); } 

Результаты работы двух методов представлены ниже. На нижнем изображении виден результат применения шаблона.

Мы отправили одно и то же письмо с использованием обоих доступных нам методов. Для того чтобы можно было увидеть отличия. В качестве примера к письму были прикреплены изображение и документ в формате PDF
Также была продемонстрирована работа с динамическим контентом и шаблонами. Разница в использовании шаблона от динамического контента состоит в том, что для шаблона указывается метка.

Данная метка в будущем будет заменена на ее содержание. А для динамического контента в HTML теге указывается следующий атрибут.

где, section-name – уникальный идентификатор, означающий, что данные указанного идентификатора будут помещены в соответствующий HTML тег. Так же стоит учесть, что элементы шаблона указанные в поле “global_merge_vars” (см. табл. 1), будут заменены на соответствующие элементы, указанные в поле “vars” структуры “merge_vars” для указанных email адресов в поле “rcpt” структуры “merge_vars”.

Рассмотрим следующий пример:

'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' 			) 		) 	) ) 

Здесь переопределение метки произойдет только для получателя с адресом “example_1@gmail.com”. Соответственно метка в шаблоне с именем “NAME”, будет заменена на имя “Alex”, для остальных получателей содержание метки останется “Lucas”.
При использовании обоих методов для отправки писем необходимо учитывать следующие факторы:

• При использовании метода send():
  
  • Если в структуре данных (см. табл. 1) указано поле “html” и оно содержит некие данные, то поле “text” будет им перекрыто.

• При использовании метода sendTemplate():
  
  • Если в редакторе шаблонов (см. выше) шаблон имеет формат “HTML”, то ни одно из двух полей: “html” и “text” не сможет перекрыть текст шаблона;
  • Если в редакторе шаблонов, шаблон имеет формат “Text”, то для его автоматической подстановки в шаблон письма при отправке, запрещено указывать в структуре данных поля: “html” и “text”. Вернее указывать можно, но они не должны содержать никаких данных, иначе в тело письма пойдут данные указанные в одном из двух полей в порядке приоритета (html, text);
  • Если в шаблоне не заполнить поле “subject”, то приоритет перейдет к одноименному полю (при наличии такового) в структуре данных (см. табл. 1).

Перечень возможных ошибок содержится в табл. 4.

Таблица 4. Перечень возможных ошибок, при неудавшейся отправке письма

ссылка на оригинал статьи http://habrahabr.ru/post/256055/