Метод createEmailMessage

Метод для создания e-mail сообщения без отправки. Непосредственно отправка осуществляется с помощью другого метода — createCampaign

Обратите внимание, что максимальный размер e-mail сообщения - 8мб.

Принцип использования

Синтаксис и URL для вызова метода

createEmailMessage (string sender_name, string sender_email, 

string subject, string body, int list_id [, string tag, string array attachments, 

string lang, string wrap_type, 

string text_body, bool generate_text, string categories])

https://api.unisender.com/ru/api/createEmailMessage?format=json&api_key=KEY&sender_name=FROMNAME&sender_email=

FROMMAIL&subject=SUBJECT&body=HTMLBODY &list_id=X&tag=

TAG&attachements=FILESARRAY&lang=LANG&wrap_type=STRING&text_body=

TEXTBODY&generate_text=GENERATETEXT &categories=CATEGORIES

Аргументы
api_key * Ключ доступа к API
sender_name * Имя отправителя. Произвольная строка, не совпадающая с e-mail адресом (аргумент sender_email).
sender_email * E-mail адрес отправителя. Этот e-mail должен быть проверен (для этого надо создать вручную хотя бы одно письмо с этим обратным адресом через веб-интерфейс, затем нажать на ссылку «отправьте запрос подтверждения» и перейти по ссылке из письма).
subject * Строка с темой письма. Может включать поля подстановки. Параметр не обязателен, если указывается template_id
body *

Текст письма в формате HTML с возможностью добавлять поля подстановки.

Вы можете вставить изображение, передав его как файл-вложение (см. описание аргумента attachments).

Если вы передаёте текст HTML целиком, то тестируйте такие письма дополнительно – заголовки вне body могут быть подвергнуты модификациям.

Параметр не обязателен, если указывается template_id

list_id * Код списка, по которому будет произведена отправка e-mail рассылки. Коды всех списков можно получить с помощью вызова getLists. Отправка письма возможна только по одному списку. Для отправки по другому списку надо создавать новое письмо. Параметр не обязателен, если указывается template_id
text_body Текстовый вариант письма. По умолчанию отсутствует. Если вы не предоставляете текстовый вариант наряду с HTML-вариантом, рекомендуем установить параметер generate_text в 1 для автоматической генерации текстовой части письма.
generate_text 0 или 1, по умолчанию 0. Значение 1 означает, что генерация текстовой части письма будет выполнена автоматически по HTML-части. Если вы не предоставляете текстовый вариант наряду с HTML-вариантом, рекомендуем установить параметер generate_text в 1 для автоматической генерации текстовой части письма.

В случае, если с помощью параметра text_body предоставляется текстовый вариант письма, то параметр generate_text игнорируется. При этом, если значение generate_text было установлено в 1, отклик сервера будет содержать предупреждение (warning).
raw_body Предназначен для сохранения json структуры структуры данных блочного редактора (при значении message_format=block). Параметр принимает только JSON-структуру, в противном случае не будет передан.
message_format

Определяет способ создания письма: "block" - блочный редактор, "raw_html" - html редактор, "text" - текст.

  • Если передать в этом параметре значение "text", то в случае, если оба параметра body и text_body будут заполнены, параметр body будет проигнорирован, а письмо будет создано из данных, переданных в параметре text_body.
  • Если передать в этом параметре значение "block", но не задать raw_body, тогда письмо будет сохранено как raw_html.
  • Если передать в этом параметре значение "block", для того, чтобы сообщение было сохранено в формате блочного редактора, обязательно должны быть переданы параметры body и raw_body.
tag Метка. Если задана, то отправка рассылки письма будет производиться не по всему списку, а только по тем адресатам, которым присвоена заданная метка.
attachments

Ассоциативный массив файлов-вложений. В качестве ключа указывается имя файла, в качестве значения - бинарное содержимое файла (base64 использовать нельзя!), например:

attachments[quotes.txt]=text%20file%content

 

Используя скрипт PHP, содержимое файла можно получить через функцию file_get_contents. Например: $api_query = array(....,"attachments[test.pdf]"=>file_get_contents('test.pdf'),...);

В сообщение вложения будут добавлены в том же порядке, в котором перечислены. Можно вставлять в текст письма inline-картинки, добавляя их как файлы-вложения и ссылаясь на них в HTML так: img src="3_name.jpg" . Вместо числа три надо подставить порядковый номер вложения, а вместо name.jpg - имя вложения.

Файл аттача должен быть только латиницей с расширением.

lang Двухбуквенный код языка для автоматически добавляемой в каждое письмо строки со ссылкой отписки. 

Если не указан, то используется код языка из URL-обращения к API.

Кроме собственно строки со ссылкой отписки, этот язык также влияет на интрефейс страницы отписки. Полностью поддерживаются языки ruit, ua и en, для нескольких других языков (da, de, es, fr, nl, pl, pt, tr) будет переведена строка со ссылкой, а интерфейс управления будет на английском.
template_id

id шаблона письма, созданного ранее, на основе которого можно создать письмо. Значение можно получить с помощью getTemplates или listTemplates. Передав этот параметр, можно не заполнять обязательные параметры subject, body, list_id, а также text_body и lang. Эти значения будут подтянуты из соответствующих параметров шаблона, id которого был указан.

Если любой из указанных параметров все же будет передан, то система проигнорирует подтянутый из параметров шаблона параметр и будет использован параметр, переданный явно в данном методе.

Если параметр template_id не указан, для создания письма не будут использованы шаблоны 

wrap_type Выравнивание текста сообщения по заданному краю. Если аргумент отсутствует, то выравнивание производиться не будет. Может иметь значения: skip (не применять), right (выравнивание по правому краю), left (выравнивание по левому краю), center (выравнивание по центру).
categories Категории письма, перечисленные в текстовом виде через запятую

Возвращаемое значение
JSON-объект с одним полем message_id, в котором содержится уникальный код сообщения – целое положительное 31-битное число. Используется для отправки сообщения методом createCampaign.

Пример возвращаемого значения:

{"result":{"message_id":357088}}

{"error":"unchecked sender email","code":"invalid_arg","result":""}
      

Примеры на PHP

Мы настоятельно рекомендуем использовать POST-запросы, так как это более безопасный метод передачи данных, нежели GET. Используйте SSL-соединение с UniSender. Подробнее о методах соединения здесь.

Пример с использованием POST-запроса
// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxxxxxx";
// Параметры создаваемого email-сообщения
// Если скрипт в кодировке UTF-8, удалите вызовы iconv
$email_from_name = iconv('cp1251', 'utf-8', "Пал Палыч");
$email_from_email = "pal.palych@yandex.ru";
$email_subject = iconv('cp1251', 'utf-8', "Тема нового e-mail сообщения");
$email_to = "354168"; // код списка, по которому делать рассылку
$email_text = iconv('cp1251', 'utf-8', "
Привет, , ". "вот ". "наша рассылка
");
$email_wrap = 'center';
$email_categories = 'letter list, test, with attachment, unisender';

// Прикрепим простой текстовый файл:
$email_attach_file_name = iconv('cp1251', 'utf-8', "текстовый файл.txt");
$email_attach_file_content = iconv('cp1251', 'utf-8', "Содержимое файла");

// Создаём POST-запрос
$POST = array (
'api_key' => $api_key,
'sender_name' => $email_from_name,
'sender_email' => $email_from_email,
'subject' => $email_subject,
'list_id' => $email_to,
'wrap_type' => $email_wrap,
'categories' => $email_categories,
'body' => $email_text,
'attachments[' . $email_attach_file_name . ']' => $email_attach_file_content
);

// Устанавливаем соединение
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $POST);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_URL,
'https://api.unisender.com/ru/api/createEmailMessage?format=json');
$result = curl_exec($ch);

if ($result) {
// Раскодируем ответ API-сервера
$jsonObj = json_decode($result);

if(null===$jsonObj) {
// Ошибка в полученном ответе
echo "Invalid JSON";

}
elseif(!empty($jsonObj->error)) {
// Ошибка создания сообщения
echo "An error occured: " . $jsonObj->error . "(code: " . $jsonObj->code . ")";

} else {
// Новое сообщение успешно создано
echo "Success. Message ID is " . $jsonObj->result->message_id;

}
} else {
// Ошибка соединения с API-сервером
echo "API access error";
}
Пример с использованием GET-запроса
 
// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxxxx";

// Параметры создаваемого email-сообщения
// Если скрипт в кодировке UTF-8, удалите вызовы iconv
$email_from_name = urlencode(iconv('cp1251', 'utf-8', "Пал Палыч"));
$email_from_email = urlencode("pal.palych@yandex.ru");
$email_subject = urlencode(iconv('cp1251', 'utf-8', "Тема нового e-mail сообщения"));
$email_to = "354168"; // код списка, по которому делать рассылку
$email_text = urlencode(iconv('cp1251', 'utf-8', "<p>Привет, , ".
"<font color='red' size='+2'>вот</font> <b>".
"наша</b> рассылка</p>"));
$email_categories = urlencode('letter list, test, with attachment, unisender');

// Прикрепим простой текстовый файл:
$email_attach_file_name = urlencode(iconv('cp1251', 'utf-8', "текстовый файл.txt"));
$email_attach_file_content = urlencode(iconv('cp1251', 'utf-8', "Содержимое файла"));

// Создаём GET-запрос
$api_url = "https://api.unisender.com/ru/api/createEmailMessage?format=json".
"&api_key=$api_key&sender_name=$email_from_name".
"&sender_email=$email_from_email".
"&subject=$email_subject&list_id=$email_to&body=$email_text".
"&attachments[$email_attach_file_name]=$email_attach_file_content".
"&categories=$email_categories";

// Делаем запрос на API-сервер
$result = file_get_contents($api_url);

if ($result) {
// Раскодируем ответ API-сервера
$jsonObj = json_decode($result);

if(null===$jsonObj) {
// Ошибка в полученном ответе
echo "Invalid JSON";

}
elseif(!empty($jsonObj->error)) {
// Ошибка создания сообщения
echo "An error occured: " . $jsonObj->error . "(code: " . $jsonObj->code . ")";

} else {
// Новое сообщение успешно создано
echo "Success. Message ID is " . $jsonObj->result->message_id;
}

} else {
// Ошибка соединения с API-сервером
echo "API access error";
}