Email API

createEmailMessage

Создает email-сообщение.

POST https://api.wavesend.ru/json/1.3/createEmailMessage

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

Имя	Тип	Обязательный	Описание
auth	string	Да	API access token из Wavesend Control Panel.
application	string	Да	Application code Wavesend
notifications	array	Да	Массив JSON, содержащий детали email-сообщения. См. таблицу Параметры Notifications ниже.

Параметры Notifications

Имя	Тип	Обязательный	Описание
send_date	string	Да	Определяет, когда отправить email. Формат: YYYY-MM-DD HH:mm или "now".
preset	string	Да	Код Preset email. Скопируйте из адресной строки Email Templates Editor в Wavesend Control Panel.
subject	string или object	Нет	Тема email-сообщения. Email всегда будет на языке контента. Если subject не содержит соответствующего content языка, тема будет пустой.
content	string или object	Нет	Содержимое тела email. Может быть строкой для простого HTML-контента или объектом для локализованных версий.
attachments	array	Нет	Вложения email. Доступно только два вложения. Каждое вложение не должно превышать 1 МБ (в кодировке base64).
list_unsubscribe	string	Нет	Позволяет переопределить URL для “Link-Unsubscribe” заголовка в письме.
campaign	string	Нет	Код Campaign для связи email с определенной кампанией.
ignore_user_timezone	boolean	Нет	Если true, отправляет email немедленно, игнорируя часовые пояса пользователей.
timezone	string	Нет	Отправляет email в соответствии с часовым поясом пользователя. Пример: "America/New_York".
filter	string	Нет	Отправляет email пользователям, соответствующим определенному условию фильтра.
devices	array	Нет	Список email-адресов (максимум 1000) для отправки целевых сообщений. При использовании сообщение отправляется только по этим адресам. Игнорируется, если используется группа приложений (Application Group).
use_auto_registration	boolean	Нет	Если true, автоматически регистрирует email-адреса из параметра devices.
users	array	Нет	Если установлено, email-сообщение будет доставлено только указанным User ID (зарегистрированным через вызов /registerEmail). Не более 1000 User ID в массиве. Если указан параметр “devices”, параметр “users” будет проигнорирован.
dynamic_content_placeholders	object	Нет	Плейсхолдеры для динамического контента вместо значений тегов устройства.
conditions	array	Нет	Условия сегментации с использованием тегов. Пример: [["Country", "EQ", "BR"]].
from	object	Нет	Укажите пользовательское имя и email отправителя, переопределяя значения по умолчанию в свойствах приложения.
reply-to	object	Нет	Укажите пользовательский email для ответа, переопределяя значение по умолчанию в свойствах приложения.
transactionId	string	Нет	Уникальный идентификатор сообщения для предотвращения повторной отправки в случае проблем с сетью. Хранится на стороне Wavesend в течение 5 минут.
capping_days	integer	Нет	Количество дней (максимум 30) для применения frequency capping на устройство. Примечание: Убедитесь, что Global frequency capping настроен в Control Panel.
capping_count	integer	Нет	Максимальное количество email-сообщений, которое может быть отправлено из определенного приложения на конкретное устройство в течение периода capping_days. Если созданное сообщение превышает лимит capping_count для устройства, оно не будет отправлено на это устройство.
capping_exclude	boolean	Нет	Если установлено значение true, этот email не будет учитываться при ограничении частоты для будущих email-сообщений.
capping_avoid	boolean	Нет	Если установлено значение true, capping не будет применяться к этому конкретному email.
send_rate	integer	Нет	Ограничивает количество сообщений, которые можно отправлять в секунду всем пользователям. Помогает предотвратить перегрузку бэкенда при массовых рассылках.
send_rate_avoid	boolean	Нет	Если установлено значение true, ограничение скорости не будет применяться к этому конкретному письму.

Пример запроса

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // обязательно. API access token из Wavesend Control Panel
    "application": "APPLICATION_CODE",  // обязательно. Application code Wavesend.
    "notifications": [{
      "send_date": "now",               // обязательно. YYYY-MM-DD HH:mm ИЛИ 'now'
      "preset": "ERXXX-32XXX",          // обязательно. Скопируйте код пресета Email из адресной строки
                                        //           страницы Email Templates Editor в Wavesend Control Panel.
      "subject": {                      // опционально. Тема email-сообщения.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // опционально. Содержимое тела email.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // опционально. Вложения email
        "name": "image.png",            //           "name" - имя файла
        "content": "iVBANA...AFTkuQmwC" //           "content" - содержимое файла в кодировке base64
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // опционально. Позволяет переопределить URL для "Link-Unsubscribe" заголовка в письме.
      "campaign": "CAMPAIGN_CODE",      // опционально. Чтобы назначить это email-сообщение определенной кампании,
                                        //           добавьте сюда код Campaign.
      "ignore_user_timezone": true,     // опционально.
      "timezone": "America/New_York",   // опционально. Укажите, чтобы отправить сообщение в соответствии с
                                        //           часовым поясом, установленным на устройстве пользователя.
      "filter": "FILTER_NAME",          // опционально. Отправка сообщения определенным пользователям, отвечающим условиям фильтра.
      "devices": [                      // опционально. Укажите email-адреса для отправки целевых сообщений.
        "email_address1",               //           Не более 1000 адресов в массиве.
        "email_address2"                //           Если установлено, сообщение будет отправлено только на адреса из
      ],                                //           списка. Игнорируется, если используется группа приложений (Application Group).
      "use_auto_registration": true,    // опционально. Автоматически регистрировать email-адреса, указанные в параметре "devices"
      "users": [                        // опционально. Если установлено, email-сообщение будет доставлено только
        "userId1",                      //           указанным User ID (зарегистрированным через вызов /registerEmail).
        "userId2"                       //           Не более 1000 User ID в массиве.
      ],                                //           Если указан параметр "devices",
                                        //           параметр "users" будет проигнорирован.
      "dynamic_content_placeholders": { // опционально. Плейсхолдеры для динамического контента вместо значений тегов устройства.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // опционально. Условия сегментации, см. примечание ниже.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // опционально. Укажите имя отправителя и адрес email отправителя,
        "name": "alias from",           //           чтобы заменить значения по умолчанию "Имя отправителя" и "Email отправителя",
        "email": "from-email@email.com" //           установленные в свойствах приложения.
      },
      "reply-to": {                     // опционально. Укажите email-адрес для замены
        "name": "alias reply to ",      //           "Email для ответа" по умолчанию, установленного в свойствах приложения.
        "email": "reply-to@email.com"
      },
      "transactionId": "unique UUID",   // опционально. Уникальный идентификатор сообщения для предотвращения повторной отправки
                                        //           в случае проблем с сетью. Хранится на стороне
                                        //           Wavesend в течение 5 минут.
      // Параметры Frequency capping. Убедитесь, что Global frequency capping настроен в Control Panel.
      "capping_days": 30,               // опционально. Количество дней для frequency capping (макс. 30 дней)
      "capping_count": 10,              // опционально. Максимальное количество email-сообщений, которое может быть отправлено с
                                        //           конкретного приложения на конкретное устройство в течение периода 'capping_days'
                                        //           . Если созданное сообщение превышает
                                        //           лимит 'capping_count' для устройства, оно не
                                        //           будет отправлено на это устройство.
      "capping_exclude": true,          // опционально. Если установлено значение true, этот email не будет
                                        //           учитываться при ограничении частоты для будущих email-сообщений.
      "capping_avoid": true,            // опционально. Если установлено значение true, ограничение частоты не будет применяться к
                                        //           этому конкретному email.
      "send_rate": 100,                 // опционально. Лимит скорости отправки.
                                        //           Ограничивает количество сообщений, которые можно отправлять в секунду всем пользователям.
                                        //           Помогает предотвратить перегрузку бэкенда при массовых рассылках.
      "send_rate_avoid": true,          // опционально. Если установлено значение true, лимит скорости отправки
                                        //           не будет применяться к этому конкретному письму.
    }]
  }
}

Примеры ответа

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

403

{
  "status_code": 403,
  "status_message": "Ограничения токена запрещают эту операцию",
  "response": null
}

Условия для тегов

Каждое условие для тега — это массив вида [tagName, operator, operand], где

• tagName: имя тега
• operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
• operand: string | integer | array | date

Описание операнда

• EQ: значение тега равно операнду;
• IN: значение тега пересекается с операндом (операнд всегда должен быть массивом);
• NOTEQ: значение тега не равно операнду;
• NOTIN: значение тега не пересекается с операндом (операнд всегда должен быть массивом);
• GTE: значение тега больше или равно операнду;
• LTE: значение тега меньше или равно операнду;
• BETWEEN: значение тега больше или равно минимальному значению операнда, но меньше или равно максимальному значению операнда (операнд всегда должен быть массивом).

Строковые теги

Допустимые операторы: EQ, IN, NOTEQ, NOTIN
Допустимые операнды:

• EQ, NOTEQ: операнд должен быть строкой;
• IN, NOTIN: операнд должен быть массивом строк вида ["value 1", "value 2", "value N"];

Целочисленные теги

Допустимые операторы: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Допустимые операнды:

• EQ, NOTEQ, GTE, LTE: операнд должен быть целым числом;
• IN, NOTIN: операнд должен быть массивом целых чисел вида [value 1, value 2, value N];
• BETWEEN: операнд должен быть массивом целых чисел вида [min_value, max_value].

Теги даты

Допустимые операторы: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Допустимые операнды:

• "YYYY-MM-DD 00:00" (строка)
• unix timestamp 1234567890 (целое число)
• "N days ago" (строка) для операторов EQ, BETWEEN, GTE, LTE

Логические теги

Допустимые операторы: EQ
Допустимые операнды: 0, 1, true, false

Теги-списки

Допустимые операторы: IN
Допустимые операнды: операнд должен быть массивом строк вида ["value 1", "value 2", "value N"].

Danger

Помните, что параметры filter и conditions не следует использовать вместе.
Кроме того, оба они будут проигнорированы, если в том же запросе используется параметр devices.

Note

Теги страны и языка

Значение тега языка — это двухбуквенный код в нижнем регистре согласно ISO-639-1
Значение тега страны — это двухбуквенный код в ВЕРХНЕМ РЕГИСТРЕ согласно ISO_3166-2
Например, чтобы отправить push-уведомление подписчикам из Бразилии, говорящим на португальском языке, вам нужно будет указать следующее условие: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

registerEmail

Регистрирует email-адрес для приложения.

POST https://api.wavesend.ru/json/1.3/registerEmail

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Device API token для доступа к Device API. Замените XXXX на ваш реальный Device API token.

Тело запроса

Имя	Тип	Описание
application*	string	Application code Wavesend
email*	string	Email-адрес.
language	string	Языковая локаль устройства. Должен быть двухбуквенным кодом в нижнем регистре в соответствии со стандартом ISO-639-1.
userId	string	User ID для связи с email-адресом.
tz_offset	integer	Смещение часового пояса в секундах.
tags	object	Значения тегов для присвоения зарегистрированному устройству.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Пример

{
  "request": {
    "application": "APPLICATION_CODE",   // обязательно. Application code Wavesend.
    "email":"email@domain.com",          // обязательно. Email-адрес для регистрации.
    "language": "en",                    // опционально. Языковая локаль.
    "userId": "userId",                  // опционально. User ID для связи с email-адресом.
    "tz_offset": 3600,                   // опционально. Смещение часового пояса в секундах.
    "tags": {                            // опционально. Значения тегов для установки на зарегистрированном устройстве.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // устанавливает список значений для тегов типа List
       "DateTag": "2024-10-02 22:11",    // обратите внимание, что время должно быть в UTC
       "BooleanTag": true                // допустимые значения: true, false
    }
  }
}

deleteEmail

Удаляет email-адрес из вашей базы пользователей.

POST https://api.wavesend.ru/json/1.3/deleteEmail

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Device API token для доступа к Device API. Замените XXXX на ваш реальный Device API token.

Тело запроса

Имя	Тип	Описание
application	string	Application code Wavesend
email	string	Email-адрес, использованный в запросе /registerEmail.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Пример

{
  "request": {
    "application": "APPLICATION_CODE",  // обязательно. Application code Wavesend
    "email": "email@domain.com"         // обязательно. Email для удаления из подписчиков приложения.
  }
}

setEmailTags

Устанавливает значения тегов для email-адреса.

POST https://api.wavesend.ru/json/1.3/setEmailTags

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Device API token для доступа к Device API. Замените XXXX на ваш реальный Device API token.

Тело запроса

Имя	Тип	Описание
application	string	Application code Wavesend
email	string	Email-адрес.
tags	object	Объект JSON с тегами для установки, отправьте ‘null’ для удаления значения.
userId	string	User ID, связанный с email-адресом.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}

Пример

{
  "request": {
    "email": "email@domain.com",                  // обязательно. Email-адрес, для которого устанавливаются теги.
    "application": "APPLICATION_CODE",            // обязательно. Application code Wavesend.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // время в UTC
      "BooleanTag": true                          // допустимые значения: true, false
    },
    "userId": "userId"                            // опционально. User ID, связанный с email-адресом.
  }
}

Note

Для других типов устройств будет возвращен 200 OK, хотя теги не будут сохранены.

Caution

Пожалуйста, избегайте установки более 50 значений тегов в одном запросе /setEmailTags.

registerEmailUser

Связывает внешний User ID с указанным email-адресом.

POST https://api.wavesend.ru/json/1.3/registerEmailUser

Note

Обратите внимание, что этот метод не регистрирует email-адрес в вашей базе пользователей; его следует использовать только для назначения User ID email-адресам, которые уже были зарегистрированы запросом /registerEmail.

Может использоваться в вызове API /createEmailMessage (параметр ‘users’).

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Device API token для доступа к Device API. Замените XXXX на ваш реальный Device API token.

Тело запроса

Имя	Тип	Описание
application*	string	Application code Wavesend
email*	string	Email-адрес.
userId*	string	User ID для связи с email-адресом.
tz_offset	integer	Смещение часового пояса в секундах.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

400

{
  "status_code": 400,
  "status_message": "Формат запроса недействителен."
}

403

{
  "status_code": 403,
  "status_message": "Запрещено."
}

Пример

{
  "request": {
    "application": "APPLICATION_CODE", // обязательно. Application code Wavesend.
    "email": "email@domain.com",       // обязательно. Email-адрес пользователя.
    "userId": "userId",                // обязательно. User ID для связи с email-адресом.
    "tz_offset": 3600                  // опционально. Смещение часового пояса в секундах.
  }
}

Note

Чтобы получить данные о soft bounces, hard bounces и Email Complaints, включая дату, email-адрес и причину каждого возврата, используйте метод BouncedEmails.