Email API

Метод /createEmailMessage устарел

Новым интеграциям следует использовать Messaging API v2 — передайте platforms: ["EMAIL"] и блок email_payload в Notify. См. руководство по миграции.

createEmailMessage Устарел

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

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

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

Название	Тип	Обязательно	Описание
auth	string	Да	Токен доступа к API из панели управления Pushwoosh.
application	string	Да	Код приложения Pushwoosh
notifications	array	Да	Массив JSON, содержащий детали email-сообщения. См. таблицу Параметры уведомлений ниже.

Параметры уведомлений

Название	Тип	Обязательно	Описание
send_date	string	Да	Определяет, когда отправлять email. Формат: YYYY-MM-DD HH:mm или "now".
preset	string	Да	Код пресета email. Скопируйте из URL-адреса в редакторе контента email в панели управления Pushwoosh.
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	Нет	Код кампании для связи email с определенной кампанией.
ignore_user_timezone	boolean	Нет	Если true, отправляет email немедленно, игнорируя часовые пояса пользователей.
timezone	string	Нет	Отправляет email в соответствии с часовым поясом пользователя. Пример: "America/New_York".
filter	string	Нет	Отправляет email пользователям, соответствующим определенному условию фильтра.
devices	array	Нет	Список email-адресов (максимум 1000) для отправки целевых email-сообщений. При использовании сообщение отправляется только по этим адресам. Игнорируется, если используется группа приложений.
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 для ответа, переопределяя значение по умолчанию в свойствах приложения.
bcc	array	Нет	BCC (скрытая копия): массив email-адресов, которые получат копию письма, не будучи видимыми для других получателей.
email_type	string	Нет	Укажите тип email: "marketing" или "transactional". Если не указано, пользователи с PW_ControlGroup: true не получат сообщение.
email_category	string	Обязательно, когда email_type равен "marketing".	Укажите одно из названий категорий, настроенных в центре управления подписками (например, Newsletter, Promotional, Product Updates).
transactionId	string	Нет	Уникальный идентификатор сообщения для предотвращения повторной отправки в случае проблем с сетью. Хранится на стороне Pushwoosh в течение 5 минут.
capping_days	integer	Нет	Количество дней (максимум 30), в течение которых будет применяться ограничение частоты для каждого устройства. Примечание: Убедитесь, что в Control Panel настроено глобальное ограничение частоты.
capping_count	integer	Нет	Максимальное количество email-сообщений, которое может быть отправлено из определенного приложения на конкретное устройство в течение периода 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 из панели управления Pushwoosh
    "application": "APPLICATION_CODE",  // обязательно. Код приложения Pushwoosh.
    "notifications": [{
      "send_date": "now",               // обязательно. YYYY-MM-DD HH:mm  ИЛИ 'now'
      "preset": "ERXXX-32XXX",          // обязательно. Скопируйте код пресета email из URL-адреса
                                        //           страницы редактора контента email в панели управления Pushwoosh.
      "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-сообщение определенной кампании,
                                        //           добавьте сюда код кампании.
      "ignore_user_timezone": true,     // необязательно.
      "timezone": "America/New_York",   // необязательно. Укажите для отправки сообщения в соответствии с
                                        //           часовым поясом, установленным на устройстве пользователя.
      "filter": "FILTER_NAME",          // необязательно. Отправить сообщение определенным пользователям, соответствующим условиям фильтра.
      "devices": [                      // необязательно. Укажите email-адреса для отправки целевых email-сообщений.
        "email_address1",               //           Не более 1000 адресов в массиве.
        "email_address2"                //           Если установлено, сообщение будет отправлено только на адреса из
      ],                                //           списка. Игнорируется, если используется группа приложений.
      "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"
      },
      "bcc": [                          // необязательно. BCC: массив email-адресов, которые получат копию, не будучи видимыми для других получателей.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // необязательно. "marketing" или "transactional".
                                        // Если не указано, пользователи с PW_ControlGroup: true не получат сообщение.
      "email_category": "category name",// обязательно, когда email_type равен "marketing". Название категории.
      "transactionId": "unique UUID",   // необязательно. Уникальный идентификатор сообщения для предотвращения повторной отправки
                                        //           в случае проблем с сетью. Хранится на стороне
                                        //           Pushwoosh в течение 5 минут.
      // Параметры ограничения частоты. Убедитесь, что глобальное ограничение частоты настроено в панели управления.
      // Ограничение частоты не применяется к транзакционным сообщениям.
      // Во всех остальных случаях, включая пропущенный "email_type", ограничение частоты применяется.
      "capping_days": 30,               // необязательно. Количество дней для ограничения частоты (максимум 30 дней)
      "capping_count": 10,              // необязательно. Максимальное количество email-сообщений, которое может быть отправлено из
                                        //           определенного приложения на конкретное устройство в течение периода '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
}

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

Каждое условие тега — это массив вида [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"].

Опасно

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

Примечание

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

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

registerEmail

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

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

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

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

Тело запроса

Название	Тип	Описание
application*	string	Код приложения Pushwoosh
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",   // обязательно. Код приложения Pushwoosh.
    "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	Да	Token XXXX	Токен устройства API для доступа к Device API. Замените XXXX вашим фактическим токеном устройства API.

Тело запроса

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

200

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

Пример

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

setEmailTags

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

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

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

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

Тело запроса

Название	Тип	Описание
application	string	Код приложения Pushwoosh
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",            // обязательно. Код приложения Pushwoosh.
    "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	Да	Token XXXX	Токен устройства API для доступа к Device API. Замените XXXX вашим фактическим токеном устройства API.

Тело запроса

Название	Тип	Описание
application*	string	Код приложения Pushwoosh
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."
}

Пример

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

Примечание

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