Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

Метод sendEmail

Метод для отправки одного индивидуального email-сообщения без использования персонализации и с ограниченными возможностями получения статистики. Разумный сценарий использования – персональное уведомление клиента о каком-то индивидуальном событии (например, изменение статуса заказа в интернет-магазине). Для массовых рассылок похожих по содержанию писем предназначена комбинация методов createEmailMessage / createCampaign.

Для отправки транзакционных писем используйте UniOneсервис транзакционных писем от UniSender.

Сообщения, отправляемые через sendEmail, не подвергаются цензуре человеком, поэтому по умолчанию количество разрешаемых к отправке писем через этот метод в сутки ограничено 1000 для новых пользователей (позже при положительных показателях статистики доставки лимит автоматически будет выше), а максимальный размер письма ограничен 1 мегабайтом.

Ограничение по количеству вызовов в минуту — 60. Минимальный интервал между отправкой одному и тому же адресату составляет 60 секунд.

Поскольку сообщения и так могут быть сделаны максимально индивидуальными, подстановка полей в них не осуществляется, за исключением значения {{UnsubscribeUrl}}.

Вы можете узнать статус доставки отправленного сообщения с помощью метода checkEmail. Для ускорения работы метода sendEmail статусы доставки хранятся ограниченное время — только месяц.

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

Синтаксис и URL для вызова метода
sendEmail (email, sender_name, sender_email, subject, body, list_id [user_campaign_id, attachments, lang, track_read, track_links, bool, string cc, array | string headers, string wrap_type, string images_as, bool error_checking, metadata])
Пример:

https://api.unisender.com/ru/api/sendEmail?format=json&api_key=KEY &email
=TONAME <EMAILTO>&sender_name=
FROMNAME&sender_email=FROMMAIL&subject=SUBJECT
&body=HTMLBODY&list_id=X&attachments[filename1]=FILE1&attachments
[filename2]=FILE2&lang=LANG&error_checking=1&metadata[meta1]=
value1&metadata[meta2]=value2

Аргументы
api_key * Ключ доступа к API
email * Адрес получателя сообщения.

Также можно передавать имя получателя:

Vasya Pupkin <vpupkin@gmail.com>

Обратите внимание, что имя должно быть перед адресом, между ними должен быть пробел.

При использовании GET-запроса для передачи кириллицы в имени необходимо кодировать строку (URL encoding)

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

Текст может включать и относительные ссылки на изображения, хранящиеся в папке пользователя на нашем сервере – такие изображения будут включены в само письмо. Ссылки на изображения на сервере должны иметь вид: «/ru/user_file?resource=images&name=IMAGE», где вместо IMAGE должно быть имя файла из вашей папки на сервере, например image.jpg или folder/image.jpg.

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

list_id * Код списка, от которого будет предложено отписаться адресату в случае, если он перейдёт по ссылке отписки. Коды всех списков можно получить с помощью вызова getLists. Если адресат отсутствует в адресной книге вашего аккаунта в системе либо отсутствует в указанном списке, он будет добавлен в базу и/или список автоматически.
user_campaign_id Ваш собственный код рассылки, к которой относится письмо. Это строка из произвольных ASCII-символов длиной до 16 символов. Рекомендуем указывать этот параметр для группировки ваших сообщений.
attachments Вложенные в письмо файлы (их бинарное содержимое, base64 использовать нельзя!).
attachments — ассоциативный массив файлов-вложений. В качестве ключа указывается имя файла, в качестве значения — содержимое файла, например:

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 — имя вложения.

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

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

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

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

track_read Принимаемое значение – 0 или 1 – отслеживать ли факт прочтения e-mail сообщения. По умолчанию 0 (не отслеживать). Если 1, то в e-mail будет добавлена ссылка на небольшую картинку, отслеживающую обращение.
track_links Принимаемое значение – 0 или 1 – отслеживать ли переходы по ссылкам в e-mail сообщениях, по умолчанию 0 (не отслеживать). Если 1, то все внешние ссылки будут заменяться на специальные, позволяющие отследить факт перехода, а затем переправить пользователя на нужную страницу.
cc Список email адресов через запятую. Содержит адреса вторичных получателей письма, которым направляется копия письма. Не более 10 элементов. Вы можете использовать параметр cc для отладки или для доказательства того, что вы отправляли письмо.
headers Текст со списком заголовков, каждый заголовок — на отдельной строке в MIME-формате. Пока поддерживаются только два заголовка, Reply-To и Priority, остальные будут проигнорированы. Пример:

Reply-To: my@email.info
Priority: normal
wrap_type Помещение HTML-текста письма в дополнительную «обёртку» из HTML-кода с целью улучшения совместимости с различными почтовыми сервисами и для выравнивание текста сообщения по заданному краю. Если аргумент отсутствует , то обёртывание будет производиться. Так же, параметр может иметь значения: skip (не применять), right(выравнивание по правому краю), left (выравнивание по левому краю), center (выравнивание по центру).
images_as Позволяет изменять режим обработки вложенных изображений в письме. Может иметь значения: attachments (поведение по умолчанию, когда параметр не задан) — картинки будут сохраняться внутри письма как вложения, only_links — посылаемые в запросе изображения будут храниться на нашем сервисе, в письме же будут отображаться только ссылки на них (это позволит уменьшить вес письма), user_default — будет использоваться один из вышеуказанных режимов, установленных для конкретного пользователя службой поддержки или реселлером. Передаваемый в запросе параметр имеет больший приоритет перед установленным для вас в профиле.
ref_key Параметр может передаваться пользователем для присвоения письму ключа-идентификатора. Принимаемое значение ключа должно быть уникальным.

Пример:
…&ref_key=123

error_checking Принимаемое значение – 0 или 1. Для обратной совместимости по умолчанию используется значение 0, но мы рекомендуем всегда передавать этот параметр со значением 1.
metadata Метаданные, отправляемые в запросе, возвращаются в Webhooks.

metadata может быть переданы в виде:

metadata[meta1]=value1&metadata[meta2]=value2
Возвращаемое значение
Пример нового формата возвращаемого значения:

{
    "result": 
        [   {"index": 0, "email": "qwe.rty@uio.com", "errors": 
                [  {"code": "unchecked_sender_email", "message": "Неподтвержденный Email отправителя"}
                ]
        }
    ]
}

Результат возвращается в таком формате при вызове с error_checking=1.

{"result":
    [   {"index":0,"email":"zzx@zzx.c", "errors":
            [   {"code":"unchecked_sender_email","message":"Неподтвержденный Email отправителя"}
            ]
        },
        {"index":1,"email":"bad@bad", "errors":
            [   {"code":"invalid_email","message":"Недопустимый Email адрес"}
            ]
        }
    ]
}

Результат возвращается в таком формате при вызове с error_checking=1 при использовании аргумента cc. Возвращаемое значение является JSON-массивом объектов (количество элементов равно количеству переданных email, с учётом cc) со следующими полями:

index Уникальный индекс email-адреса, соответствующий позиции адреса в исходном массиве получателей. Если использовался параметр cc, то могут встретиться индексы, отсутствующие в исходном массиве email — это индексы копий сообщений.
email email-адрес, на который было отправлено сообщение — соответствует адресу из аргумента email или какому-либо адресу из аргумента cc.
id Уникальный код сообщения – строка до 64 символов.
Если из-за ошибки отправка невозможна — поле id отсутствует. Ещё надо учитывать, что не все ошибки выявляются в момент приёма запроса на отправку. В этом случае сообщение принимается в обработку и получает id, а об ошибке можно узнать позднее, с помощью метода checkEmail.
errors Поле, представляющее собой массив объектов с ошибками, связанными с email-адресом. Поле присутствует только тогда, когда входные данные невалидные и отправка сообщения на указанный email-адрес невозможна. Каждый элемент массива — JSON-объект с полями code и message, где code содержит условный код ошибки, а message — описывающее ошибку сообщение.Список возможных кодов ошибок:

  • retry_later
    Временная ошибка. Попробуйте позднее (рекомендуемый таймаут — минута).
  • attachment_is_not_bytestring
    Содержимое вложения не является скалярным значением.
  • attachment_quota_error
    Превышен допустимый размер вложения.
  • body_empty
    Отсутствует тело письма.
  • body_exceeds_length
    Тело письма превышает допустимый размер.
  • empty_subject
    Не указана тема письма.
  • subject_exceeds_length
    Тема письма превышает допустимый размер.
  • wrong_header_parameter
    Не указан обязательный параметр заголовка.
  • header_not_allowed
    Указанный заголовок не поддерживается.
  • invalid_email
    Недопустимый Email-адрес.
  • empty_sender_name
    Не указано имя отправителя
  • invalid_sender_email
    Недопустимый Email-адрес отправителя.
  • unchecked_sender_email
    Email-адрес отправителя не подтвержден.
  • unsupported_lang
    Указанный язык не поддерживается системой.
  • has_been_sent
    Email данному адресату уже был отправлен
  • unsubscribe_link_missing
    Вы забыли добавить ссылку отписки:
  • unsubscribed_globally
    адрес глобально отписан от рассылок.
Пример старого формата возвращаемого значения, оставленного для совместимости:

{"result": {
    "email_id":14362456134
}

Этот формат применяется при следующих условиях: вызов должен быть без параметра error_checking или с его нулевым значением, отправка без использования аргумента ‘cc’. Тогда возвращаемое значение является JSON объектом, с единственным документированным полем:

email_id Уникальный код сообщения. Может использоваться для контроля доставки методом checkEmail.

Пример формирования URL-запроса

https://api.unisender.com/ru/api/sendEmail?format=json&api_key=KEY
&email=test@example.com&sender_name=Mike&sender_email=mike@example.com
&subject=Sample+Subject&body=Hello,+World!&list_id=112233

— отправить сообщение Hello, World на адрес test@example.org с указанием обратного адреса mike@example.com

Примеры на PHP

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

Пример с использованием POST-запроса

//ваш API-ключ
$api_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

// Параметры сообщения
$email_from_name = 'Unisender';
$email_from_email = 'test@unisender.com';
$email_to = 'test@gmail.com';
$email_body = 'Test, привет.';
$email_subject = 'test email';
$list_id = 234442;

// Создаём POST-запрос
$request = [
 'api_key' => $api_key,
 'email' => $email_to,
 'sender_name' => $email_from_name,
 'sender_email' => $email_from_email,
 'subject' => $email_subject,
 'body' => $email_body,
 'list_id' => $list_id,
 'attachments[attach.pdf]' => file_get_contents('/path/to/attach/attach.pdf'),
];


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

$result = curl_exec($ch);

if ($result) {

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

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

 } elseif (!empty($jsonObj->error)) {
 // Ошибка отправки сообщения
 echo sprintf('An error occured %s (code: %s)', $jsonObj->error, $jsonObj->code);
 } else {
 // Сообщение успешно отправлено
 echo 'Email message is sent. Message id ' . $jsonObj->result->email_id;

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