Метод для отправки одного индивидуального email-сообщения без использования персонализации и с ограниченными возможностями получения статистики. Разумный сценарий использования – персональное уведомление клиента о каком-то индивидуальном событии (например, изменение статуса заказа в интернет-магазине). Для массовых рассылок похожих по содержанию писем предназначена комбинация методов createEmailMessage / createCampaign.
Сообщения, отправляемые через sendEmail, не подвергаются цензуре человеком, поэтому по умолчанию количество разрешаемых к отправке писем через этот метод в сутки ограничено 1000 для новых пользователей (позже при положительных показателях статистики доставки лимит автоматически будет выше), а максимальный размер письма ограничен 1 мегабайтом.
Ограничение по количеству вызовов в минуту - 60. Минимальный интервал между отправкой одному и тому же адресату составляет 60 секунд.
Для отправки транзакционных писем без ограничений используйте Unisender Go — сервис транзакционных писем от Unisender.
Поскольку сообщения и так могут быть сделаны максимально индивидуальными, подстановка полей в них не осуществляется, за исключением значения {{UnsubscribeUrl}}.
Вы можете узнать статус доставки отправленного сообщения с помощью метода checkEmail. Для ускорения работы метода sendEmail статусы доставки хранятся ограниченное время - только месяц.
Принцип использования
| Синтаксис и URL для вызова метода |
| sendEmail (email, sender_name, sender_email, subject, body, list_id [attachments, lang, track_read, track_links, bool, string cc, array | string headers, string images_as, bool error_checking, metadata]) |
| Пример:
https://api.unisender.com/ru/api/sendEmail?format=json&api_key=KEY &email |
| Аргументы | |
| api_key * | Ключ доступа к API |
| email * | Адрес получателя сообщения.
Также можно передавать имя получателя: Vasya Pupkin <vpupkin@gmail.com> Обратите внимание, что имя должно быть перед адресом, между ними должен быть пробел. При использовании GET-запроса для передачи кириллицы в имени необходимо кодировать строку (URL encoding) |
| sender_name * | Имя отправителя. Произвольная строка, отображается в поле "От кого" почтового клиента. |
| 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. Если адресат отсутствует в адресной книге вашего аккаунта в системе либо отсутствует в указанном списке, он будет добавлен в базу и/или список автоматически. |
| 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=»name.jpg» . Вместо name.jpg надо подставить имя вложения. Предполагается, что HTML-текст содержит только содержимое тега body. Если вы передаёте текст HTML целиком, то тестируйте такие письма дополнительно – заголовки вне body могут быть подвергнуты модификациям. |
| lang | Двухбуквенный код языка для автоматически добавляемой в каждое письмо строки со ссылкой отписки.
Если не указан, то используется en. Кроме собственно строки со ссылкой отписки, этот язык также влияет на интерфейс страницы отписки. Полностью поддерживаются языки ru, ua, it и 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 | Содержит адрес вторичного получателя письма, которому направляется копия письма. Не более 1 адреса. Вы можете использовать параметр cc для отладки или для доказательства того, что вы отправляли письмо. Тарификация всегда происходит как за отправку отдельного письма, не входит в список используемых адресов тарифов подписки Лайт/Стандарт. |
| headers | Текст со списком заголовков, каждый заголовок - на отдельной строке в MIME-формате. Пока поддерживаются только два заголовка, Reply-To и Priority, остальные будут проигнорированы. Пример:
Reply-To: my@email.info Priority: normal |
| images_as | Позволяет изменять режим обработки вложенных изображений в письме. Может иметь значения: attachments (поведение по умолчанию, когда параметр не задан) - картинки будут сохраняться внутри письма как вложения, only_links - посылаемые в запросе изображения будут храниться на нашем сервисе, в письме же будут отображаться только ссылки на них (это позволит уменьшить вес письма), user_default - будет использоваться один из вышеуказанных режимов, установленных для конкретного пользователя службой поддержки или реселлером. Передаваемый в запросе параметр имеет больший приоритет перед установленным для вас в профиле. |
| ref_key | Параметр может передаваться пользователем для присвоения письму ключа-идентификатора. Принимаемое значение ключа должно быть уникальным.
Пример: |
| 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 или какому-либо адресу из аргумента cc. | |
| id | Уникальный код сообщения – строка до 64 символов. Если из-за ошибки отправка невозможна - поле id отсутствует. Ещё надо учитывать, что не все ошибки выявляются в момент приёма запроса на отправку. В этом случае сообщение принимается в обработку и получает id, а об ошибке можно узнать позднее, с помощью метода checkEmail. |
| errors | Поле, представляющее собой массив объектов с ошибками, связанными с email-адресом. Поле присутствует только тогда, когда входные данные невалидные и отправка сообщения на указанный email-адрес невозможна. Каждый элемент массива - JSON-объект с полями code и message, где code содержит условный код ошибки, а message - описывающее ошибку сообщение.Список возможных кодов ошибок:
|
Пример старого формата возвращаемого значения, оставленного для совместимости:
{"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
