Email API

createEmailMessage

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

POST https://api.pushwoosh.com/json/1.3/createEmailMessage

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

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

Параметры Notifications

Имя	Тип	Обязательно	Описание
send_date	string	Да	Определяет, когда отправить письмо. Формат: YYYY-MM-DD HH:mm или "now".
preset	string	Да	Email preset code. Скопируйте из адресной строки Email Content Editor в Pushwoosh Control Panel.
subject	string или object	Нет	Тема письма. Письмо всегда будет на языке контента. Если subject не содержит соответствующего языка для content, тема будет пустой.
content	string или object	Нет	Содержимое тела письма. Может быть строкой для простого HTML-контента или объектом для локализованных версий.
attachments	array	Нет	Вложения письма. Доступно только два вложения. Каждое вложение не должно превышать 1 МБ (в кодировке base64).
list_unsubscribe	string	Нет	Позволяет установить кастомный URL для заголовка “Link-Unsubscribe”.
campaign	string	Нет	Campaign code для связывания письма с конкретной кампанией.
ignore_user_timezone	boolean	Нет	Если true, отправляет письмо немедленно, игнорируя часовые пояса пользователей.
timezone	string	Нет	Отправляет письмо в соответствии с часовым поясом пользователя. Пример: "America/New_York".
filter	string	Нет	Отправляет письмо пользователям, соответствующим конкретному условию фильтра.
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 для ответа (reply-to), переопределяя значение по умолчанию в свойствах приложения.
transactionId	string	Нет	Уникальный идентификатор сообщения для предотвращения повторной отправки в случае проблем с сетью. Хранится на стороне Pushwoosh в течение 5 минут.
capping_days	integer	Нет	Количество дней (макс. 30) для применения ограничения частоты (frequency capping) на устройство. Примечание: Убедитесь, что Global frequency capping настроен в Control Panel.
capping_count	integer	Нет	Максимальное количество писем, которое может быть отправлено из конкретного приложения на конкретное устройство в течение периода capping_days. Если созданное сообщение превышает лимит capping_count для устройства, оно не будет отправлено на это устройство.
capping_exclude	boolean	Нет	Если установлено в true, это письмо не будет учитываться в ограничении частоты для будущих писем.
capping_avoid	boolean	Нет	Если установлено в true, ограничение частоты не будет применяться к этому конкретному письму.
send_rate	integer	Нет	Ограничивает количество сообщений, отправляемых в секунду всем пользователям. Помогает предотвратить перегрузку бэкенда при больших объемах отправки.
send_rate_avoid	boolean	Нет	Если установлено в true, лимит троттлинга не будет применяться к этому конкретному письму.

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

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // обязательно. API access token из Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // обязательно. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // обязательно. YYYY-MM-DD HH:mm ИЛИ 'now'
      "preset": "ERXXX-32XXX",          // обязательно. Скопируйте Email preset code из адресной строки
                                        //           страницы редактора Email Content в Pushwoosh Control Panel.
      "subject": {                      // опционально. Тема email-сообщения.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // опционально. Содержимое тела письма.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // опционально. Вложения письма
        "name": "image.png",            //           "name" - имя файла
        "content": "iVBANA...AFTkuQmwC" //           "content" - контент файла в кодировке base64
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // опционально. Позволяет установить кастомный URL для заголовка "Link-Unsubscribe"
      "campaign": "CAMPAIGN_CODE",      // опционально. Чтобы назначить это сообщение конкретной кампании,
                                        //           добавьте сюда код кампании.
      "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",           //           для замены стандартных "From name" и "From email",
        "email": "from-email@email.com" //           настроенных в свойствах приложения.
      },
      "reply-to": {                     // опционально. Укажите email-адрес для замены
        "name": "alias reply to ",      //           стандартного "Reply to", настроенного в свойствах приложения.
        "email": "reply-to@email.com"
      },
      "transactionId": "unique UUID",   // опционально. Уникальный идентификатор сообщения для предотвращения повторной отправки
                                        //           в случае проблем с сетью. Хранится на стороне
                                        //           Pushwoosh в течение 5 минут.
      // Параметры ограничения частоты. Убедитесь, что Global frequency capping настроен в Control Panel.
      "capping_days": 30,               // опционально. Количество дней для ограничения частоты (макс. 30 дней)
      "capping_count": 10,              // опционально. Максимальное количество писем, которое может быть отправлено из
                                        //           конкретного приложения на конкретное устройство в течение периода 'capping_days'.
                                        //           Если созданное сообщение превышает лимит
                                        //           'capping_count' для устройства, оно не будет
                                        //           отправлено на это устройство.
      "capping_exclude": true,          // опционально. Если установлено в true, это письмо не будет
                                        //           учитываться в ограничении частоты для будущих писем.
      "capping_avoid": true,            // опционально. Если установлено в true, ограничение частоты не будет применяться к
                                        //           этому конкретному письму.
      "send_rate": 100,                 // опционально. Лимит троттлинга.
                                        //           Ограничивает количество сообщений, отправляемых в секунду всем пользователям.
                                        //           Помогает предотвратить перегрузку бэкенда при больших объемах отправки.
      "send_rate_avoid": true,          // опционально. Если установлено в true, лимит троттлинга не будет применяться к
                                        //           этому конкретному письму.
    }]
  }
}

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

200

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

403

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

Условия тегов (Tag conditions)

Каждое условие тега представляет собой массив вида [tagName, operator, operand], где

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

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

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

Строковые теги (String tags)

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

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

Целочисленные теги (Integer tags)

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

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

Теги даты (Date tags)

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

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

Булевы теги (Boolean tags)

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

Теги списков (List tags)

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

Опасно

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

Примечание

Теги Country и Language

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

registerEmail

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

POST https://api.pushwoosh.com/json/1.3/registerEmail

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

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

Тело запроса

Имя	Тип	Описание
application*	string	Pushwoosh application code
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
}

Example

{
  "request": {
    "application": "APPLICATION_CODE",   // обязательно. Pushwoosh application code.
    "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.pushwoosh.com/json/1.3/deleteEmail

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

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

Тело запроса

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

200

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

Example

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

setEmailTags

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

POST https://api.pushwoosh.com/json/1.3/setEmailTags

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

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

Тело запроса

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

200

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

Example

{
  "request": {
    "email": "email@domain.com",                  // обязательно. Email-адрес для установки тегов.
    "application": "APPLICATION_CODE",            // обязательно. Pushwoosh application code.
    "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-адресом.
  }
}

Примечание

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

Осторожно

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

registerEmailUser

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

POST https://api.pushwoosh.com/json/1.3/registerEmailUser

Примечание

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

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

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

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

Тело запроса

Имя	Тип	Описание
application*	string	Pushwoosh application code
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": "Request format is not valid."
}

403

{
  "status_code": 403,
  "status_message": "Forbidden."
}

Example

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

Примечание

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