email/send

Метод для отправки писем вашим подписчикам.

Ограничения:

  • максимальный размер запроса - 5 MB;

  • максимальное количество получателей (recipients) – 500 email;

  • тема и тело письма должны быть заданы;

  • переменные для подстановки в объектах "substitutions", "global_substitutions" могут содержать буквы латинского алфавита, цифры, символы "_" и "-". Первым символом может быть только буква, использование пробелов не допускается.

Тестовый запрос

POST /ru/transactional/api/v1/email/send.json
{
  "api_key": "apiKey",
  "message": 
  {
    "template_engine" : "simple",
    "template_id" : "template_id",
    "global_substitutions": 
    {
      "someVar":"some val"
    },
    "global_metadata": 
    {
      "key1" : "val1"
    },
    "body": 
    {
      "html": "<b>Hello {{substitutionName}}</b>",
      "plaintext": "Some plain text",
      "amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
    },
    "subject": "Example subject",
    "from_email": "email@example.org",
    "from_name": "userName",
    "reply_to": "email@example.org",
    "track_links" : 1,
    "track_read"  : 1,
    "recipients": [
      {
        "email": "email@example.org",
        "substitutions": 
        {
          "substitutionName": "substitutionVal",
          "to_name": "Name Surname"
        },
        "metadata":
        {
           "key1" : "val1"
        }
      },
      {
        "email": "bad_email@com",
        "substitutions": 
        {
          "substitutionName": "substitutionVal",
          "UNSUB_hash": "Qwcd1789"
        }
      }
    ],
    "headers": 
    {
      "X-MyHeader": "some_useful_data"
    },
    "attachments": [
      {
        "type": "text/plain",
        "name": "myfile.txt",
        "content": "ZXhhbXBsZSBmaWxl" 
      }
    ],
    "inline_attachments": [
      {
        "type": "image/png",
        "name": "IMAGECID",
        "content": "iVBORw0KGgo" 
      }
    ],
    "options": 
    {
      "unsubscribe_url": "someurl"
    }
  }
}

Пример удачного выполнения запроса


{
  "status":"success",
  "job_id":"1ZymBc-00041N-9X",
  "emails":["email@gmail.com"]
}

 

Параметры запроса

Название Тип Описание
api_key Обязательная строка API-ключ пользователя
message Обязательный объект Объект, который содержит в себе все параметры передаваемого сообщения
message.template_engine Опциональная строка Параметр для выбора шаблонизатора. Принимает значения: “simple” и “velocity”. Если параметр не передавать, будет взято значение по умолчанию “simple”. В шаблонизаторе "simple" доступно использование переменных типа string, number. Шаблонизатор "velocity" позволяет использовать кроме типов данных string и number также array и object
message.template_id Опциональная строка (обязательная, если не передается "body") Уникальный идентификатор созданного ранее шаблона. Параметр не обязателен для передачи, если передается "body". Если передать "body", "template_id" будет проигнорирован. Как создавать шаблоны?
message.global_substitutions Опциональный объект Объект для передачи глобальных подстановок (например, название компании). Если названия переменных повторяются в объекте пользовательских подстановок "substitutions", значения переменных будут взяты из объекта "substitutions" Подстановки работают в параметрах:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • options.unsubscribe_url
  • from_name
  • headers
message.global_metadata
(устаревший синоним: message.metadata)
Опциональный объект Объект для передачи метаданных в формате: “key”: “value”. Метаданные возвращаются в Webhook. Максимальное количество ключей: 10; максимальная длина ключа: 64 символа; максимальная длина значения ключа: 1024 символа.
message.body Опциональный объект (обязателен, если не передается "template_id") Объект, который содержит в себе html, plaintext и amp части письма. Для передачи inline-вложений можно использовать массив "inline_attachments"
message.body.html Обязательная строка Html-часть письма
message.body.plaintext Опциональная строка Необязательная plaintext-часть письма
message.body.amp Опциональная строка Необязательная AMP-часть письма
message.subject Обязательная строка Тема письма
message.from_email Обязательная строка Адрес отправителя
message.from_name Опциональная строка Имя отправителя
message.reply_to Опциональная строка Адрес получателя ответа на письмо
message.track_links Опциональный логический
  • 0 - трекинг кликов отключен
  • 1 - трекинг кликов включен (значение по умолчанию)
message.track_read Опциональный логический
  • 0 - трекинг прочтений отключен
  • 1 - трекинг прочтений включен (значение по умолчанию)
message.recipients Обязательный массив объектов Содержит адреса получателей и объект с переменными для замены и их значениями
message.recipients[n].email Обязательная строка Адрес получателя
message.recipients[n].substitutions Опциональный объект Объект, описывающий подстановки для конкретного пользователя (например, имя пользователя, товар для показа именно данному пользователю - см. Шаблонизаторы). Подстановки работают в параметрах:
  •  
  • body.plaintext
  • body.amp
  • subject
  • options.unsubscribe_url
  • from_name
  • headers

message.recipients[n].substitutions. to_name

Опциональная строка Переменная для подстановки в SMTP-заголовок “To”, позволяет подставлять имя получателя. При получении письма в строке “To” адресат будет видеть: Name Surname <recipient.email@example.com>. Длина поля ограничена 78 символами.
message.recipients[n].substitutions. UNSUB_hash Опциональная строка Пример переменной, используемой для подстановки хеша в пользовательскую ссылку отписки
message.recipients[n].metadata Опциональный объект Объект для передачи метаданных, специфичных для отдельного получателя, в формате: "key": "value". Метаданные возвращаются в Webhook. Максимальное количество ключей: 10; максимальная длина ключа: 64 символа; максимальная длина значения ключа: 1024 символа.
message.headers Опциональный объект Объект, содержащий дополнительные заголовки письма, максимум 50 заголовков. Префикс "X-" в имени заголовка обязателен, заголовки без него будут проигнорированы. Впрочем, если техподдержка одобрила вам отключение ссылки отписки, то вы также можете передавать заголовки List-Unsubscribe, List-Subscribe, List-Help, List-Owner и List-Archive.
message.attachments Опциональный массив Массив, с помощью которого передаются вложения. Содержит параметры type, name, content, описывающие данный массив
message.attachments[n].type Обязательная строка Тип вложения, см. MIME. Например, "type" : "text/plain"
message.attachments[n].name Обязательная строка Имя вложения в формате: "название.расширение"
message.attachments[n].content Обязательная строка Содержимое файла в base64. Для использования в HTML должен быть передан как <img src="cid:IMAGECID">
message.inline_attachments Опциональный массив Массив для передачи inline-вложений
message.inline_attachments[n].type Обязательная строка Тип вложения, см. MIME. Например, "type": "image/png"
message.inline_attachments[n].name Обязательная строка Идентификатор вложения. Если, например, "name"="IMAGECID" то для вывода картинки из этого вложения в HTML тексте письма надо указать <img src="cid:IMAGECID">
message.inline_attachments[n].content Обязательная строка Содержимое вложения в base64.
message.skip_unsubscribe Опциональный логический
  • 0 - добавить подвал со ссылкой отписки к HTML-части письма (по умолчанию)
  • 1 - не добавлять подвал со ссылкой отписки к HTML-части (но заголовок List-Unsubscribe всё равно будет добавлен, если options.unsubscribe_url не пуст)

Для использования skip_unsubscribe=1 вам надо попросить техподдержку включить такую возможность.

message.options Опциональный объект Объект для передачи дополнительных опций.
message.options.unsubscribe_url Опциональная строка Пользовательская ссылка отписки

 

Поля успешного результата

Название Тип Описание
status Обязательная строка Значение "success"
job_id Обязательная строка Уникальный идентификатор осуществленной отправки
emails Обязательный массив Массив, содержит в себе адреса, на которые отправка прошла успешно
failed_emails Обязательный объект

Объект, содержащий адреса, на которые отправка по каким-то причинам не была осуществлена. Объект заполняется в формате: “адрес” : “состояние”

Возможные состояния адресов, на которые не удалось осуществить отправку:

unsubscribed - указанный адрес отписан;

invalid - адрес не существует, или введен некорректно;

duplicate - адрес повторяется в запросе, повторная отправка на один и тот же email предотвращена;

temporary_unavailable - адрес временно недоступен. Это значит, что в течении следующих трех суток отправка на этот адрес будет возвращать ошибку. Email может быть временно недоступным из-за того, что:

  • предыдущая отправка была отвергнута сервером получателя как спам;

  • почтовый ящик получателя переполнен;

  • домен не принимает почту из-за неверной настройки на стороне получателя;

  • домен не принимает никакую почту вообще, по любой причине;

  • ящик не используется;

  • сервер отправителя был отвергнут из-за блеклистинга;

permanent_unavailable - адрес перманентно недоступен, глобально отписан, либо в одном из предыдущих писем нажал “Это спам”

 

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

 

Пример удачного выполнения запроса, завершенного с ошибками

{
"status":"success",
"job_id":"1ZymBc-00041N-9X",
"emails":["email@gmail.com"],
"failed_emails":
{ "email1@gmail.com":"unsubscribed", "email2@gmail.com":"invalid", "email@gmail.com":"duplicate", "email3@gmail.com":"temporary_unavailable" }
}

 

Поля ошибочного результата

status - строка "error"

message - сообщение об ошибке на английском

code - один из общих кодов ошибок или код ошибки из таблицы ниже:

Код Значение Как исправить
201  Тело письма не передано Убедитесь, что тело письма передается правильно
202 Не указан адрес отправителя Укажите адрес отправителя
203 Не указана тема письма Укажите тему письма
204 Получатели письма заданы некорректно Убедитесь, что список получателей задан массивом, в котором каждый получатель является массивом, где обязательно задан параметр "email". Посмотреть пример
205 Неверный адрес отправителя Убедитесь, что параметр "email_from" заполнен верно
206 В качестве адреса отправителя используется неподтвержденный адрес Используйте адрес, находящийся на подтвержденном домене
207 MIME-тип файла не соответствует заданному Проверьте указанный тип и файл на соотвествие
208 Слишком много получателей письма Сократите количество адресатов
209 В приложенных файлах повторяются имена Переименуйте файлы с повторяющимися именами
210 В файлах, приложенных к телу письма, повторяются имена Переименуйте файлы с повторяющимися именами
211 Не указано имя приложенного файла Укажите имя приложенного файла
212 Некорректно заданы подстановки в массиве получателей (не задан массив подстановок) Убедитесь, что не превышен максимальный лимит подстановок и отсутствуют подстановки неправильного типа данных (допустимо string/integer)
213 Нет прав для использования пользовательского backend-домена Попробуйте обратиться в службу поддержки
215 Пользователь не может отправлять Попробуйте обратиться в службу поддержки
216 Данные адресатов переданы неправильно  Значение "metadata" должно быть типа string или integer. Для передачи нескольких параметров в "metadata" используйте синтаксис массива
217 Превышен лимит параметров в "metadata" Сократите количество параметров в "metadata", их должно быть не больше 10
218 Данные адресатов переданы неправильно Убедитесь, что ключ параметра "metadata" короче 64 символов
219 Данные адресатов переданы неправильно Убедитесь, что значение параметра "metadata" короче 1024 символов
220 Параметр "template_engine" принимает значения "simple"/"velocity" Проверьте значение, переданное в параметре "template_engine"
221 В запросе нет html-тега <body> Поместите html-тег <body> внутрь тега <html>. Тег <body> необходим для отображения содержимого HTML письма.
222 Размер HTML слишком велик Проверьте что размер HTML меньше 5 мегабайт
223 В "attachments" пропущено тело "content" или передано пустоту Добавьте тело "content" и укажите для него значение
224 Заголовок ‘List-Unsubscribe’ не допускается Либо удалите заголовок List-Unsubscribe из запроса, либо попросите техподдержку включить вам опцию allow_skip_unsubscribe, если хотите сами управлять отпиской.
901 Отправка заблокирована из-за превышения дневного лимита. У каждого пользователя есть максимальный дневной лимит отрпавок для предотвращения спама. Этот лимит автоматически увеличивается при успешных доставках. Вы можете либо плавно увеличивать объём отправок и лимит увеличится автоматически, либо запросить увеличение, обратившись в техподдержку.
902 Достигнут дневной лимит отправок на бесплатном тарифе. Ждите следующего дня либо переключитесь на платный тариф.
903 На бесплатном тарифе разрешена отправка только на свои собственные подтверждённые домены. Пожалуйста, подтвердите владение всеми доменами, на которые вы хотите слать письма либо переключитесь на платный тариф.
904 Недостаточно средств. Ошибка оплаты по карте. Попробуйте подключить другую карту или свяжитесь с техподдержкой для разрешения ситуации.
905 Вы достигли предела отправок по вашему тарифному плану. Обычно тарифные планы позволяют платное превышение лимита. В вашем случае это запрещено - возможно, из-за неоплаченных счетов. Пожалуйста, убедитесь, что все счета оплачены или свяжитесь с техподдержкой для решения проблемы.
908 Внутренняя ошибка, владелец проекта не найден. Свяжитесь с техподдержкой.
1506 Поле 'headers' должно быть объектом. Проверьте передаваемый JSON и используйте объект для поля "headers" (не массив, строку или какой-то другой тип)
1507 Более 50 элементов в массиве "headers". Пожалуйста, сократите количество элементов массива "headers" до 50.

 

Как изменить ссылку отписки


Сервис UniOne по умолчанию добавляет к  каждому письму футер со стандартной ссылкой отписки. Язык стандартной ссылки отписки зависит от языка выполнения запроса email/send (например, /ru/transactional/api/v1/email/send.json - язык ссылки отписки русский. Для изменения на английский поменять /ru на /en)

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

  1. Обратитесь в службу поддержки для отключения стандартной ссылки отписки;

  2. В объект "options" добавьте "unsubscribe_url" : "URL". URL - пользовательская ссылка отписки, используемая в письме. В ссылке отписки работают подстановки, таким образом, если задать в объекте "substitutions" переменную, то можно использовать эту переменную в ссылке отписки.
    Например,   
    "substitutions": {"UNSUB_hash": "Qwcd1789"}
    И
    "options": {"unsubscribe_url":"https://emlportal.com/en/v5/te_unsubscribe?hash= { {UNSUB_hash}}"}

  3. Вставить ссылку отписки в тело письма.