меню
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 [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
=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 * Имя отправителя. Произвольная строка, отображается в поле «От кого» почтового клиента.
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=»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 Содержит адрес вторичного получателя письма, которому направляется копия письма. Не более 1 адреса. Вы можете использовать параметр cc для отладки или для доказательства того, что вы отправляли письмо.
headers Текст со списком заголовков, каждый заголовок — на отдельной строке в MIME-формате. Пока поддерживаются только два заголовка, Reply-To и Priority, остальные будут проигнорированы. Пример:

Reply-To: my@email.info
Priority: normal
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-адрес отправителя не подтвержден.
  • cc_exceeded
    Превышено количество 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

Оцените, на сколько вам показалась полезной статья «Метод sendEmail»
(0)