API для Email

createEmailMessage

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

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

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

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

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

Имя	Тип	Обязательный	Описание
send_date	`string`	Да	Определяет, когда отправить email. Формат: `YYYY-MM-DD HH:mm` или `"now"`.
preset	`string`	Да	Код пресета email. Скопируйте его из адресной строки на странице редактора контента email в Панели управления Pushwoosh.
subject	`string` или `object`	Нет	Тема email. Язык письма всегда будет соответствовать языку контента. Если `subject` не содержит язык, соответствующий `content`, тема будет пустой.
content	`string` или `object`	Нет	Тело email. Может быть строкой для простого HTML-контента или объектом для локализованных версий.
attachments	`array`	Нет	Вложения в email. Доступно не более двух вложений. Каждое вложение не должно превышать 1 МБ (в кодировке base64).
campaign	`string`	Нет	Код кампании для связи email с определенной кампанией.
ignore_user_timezone	`boolean`	Нет	Если `true`, email отправляется немедленно, игнорируя часовые пояса пользователей.
timezone	`string`	Нет	Отправляет email в соответствии с часовым поясом пользователя. Пример: `"America/New_York"`.
filter	`string`	Нет	Отправляет email пользователям, соответствующим определенному условию фильтра.
devices	`array`	Нет	Список email-адресов (не более 1000) для отправки целевых писем. Если используется, сообщение отправляется только по этим адресам. Игнорируется, если используется группа приложений.
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`	Нет	Уникальный идентификатор сообщения для предотвращения повторной отправки в случае проблем с сетью. Хранится на стороне Pushwoosh в течение 5 минут.
capping_days	`integer`	Нет	Количество дней (максимум 30), в течение которых применяется ограничение частоты для каждого устройства. Примечание: Убедитесь, что глобальное ограничение частоты настроено в Панели управления.
capping_count	`integer`	Нет	Максимальное количество email, которое может быть отправлено из конкретного приложения на определенное устройство в течение периода `capping_days`. Если созданное сообщение превышает лимит `capping_count` для устройства, оно не будет отправлено на это устройство.
capping_exclude	`boolean`	Нет	Если установлено значение `true`, это письмо не будет учитываться при подсчете лимита для будущих рассылок.
capping_avoid	`boolean`	Нет	Если установлено значение `true`, ограничение частоты не будет применяться к этому конкретному письму.

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

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // обязательно. API access token из Панели управления Pushwoosh
    "application": "APPLICATION_CODE",  // обязательно. Код приложения Pushwoosh.
    "notifications": [{
      "send_date": "now",               // обязательно. YYYY-MM-DD HH:mm ИЛИ 'now'
      "preset": "ERXXX-32XXX",          // обязательно. Скопируйте код пресета email из адресной строки
                                        //           на странице редактора контента 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"
      }],
      "campaign": "CAMPAIGN_CODE",      // необязательно. Чтобы назначить это email-сообщение определенной кампании,
                                        //           добавьте код кампании сюда.
      "ignore_user_timezone": true,     // необязательно.
      "timezone": "America/New_York",   // необязательно. Укажите, чтобы отправить сообщение в соответствии
                                        //           с часовым поясом, установленным на устройстве пользователя.
      "filter": "FILTER_NAME",          // необязательно. Отправить сообщение определенным пользователям, отвечающим условиям фильтра.
      "devices": [                      // необязательно. Укажите 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",           //           чтобы заменить значения по умолчанию "Имя отправителя" и "Email отправителя"
        "email": "from-email@email.com" //           установленные в свойствах приложения.
      },
      "reply-to": {                     // необязательно. Укажите email-адрес для замены
        "name": "alias reply to ",      //           значения по умолчанию "Ответить кому", установленного в свойствах приложения.
        "email": "reply-to@email.com"
      },
      "transactionId": "unique UUID",   // необязательно. Уникальный идентификатор сообщения для предотвращения повторной отправки
                                        //           в случае проблем с сетью. Хранится на стороне
                                        //           Pushwoosh в течение 5 минут.
      // Параметры ограничения частоты. Убедитесь, что глобальное ограничение частоты настроено в Панели управления.
      "capping_days": 30,               // необязательно. Количество дней для ограничения частоты (максимум 30 дней)
      "capping_count": 10,              // необязательно. Максимальное количество email-сообщений, которое может быть отправлено из
                                        //           конкретного приложения на определенное устройство в течение периода 'capping_days'.
                                        //           Если созданное сообщение превышает
                                        //           лимит 'capping_count' для устройства, оно не
                                        //           будет отправлено на это устройство.
      "capping_exclude": true,          // необязательно. Если установлено значение true, это письмо не
                                        //           будет учитываться при подсчете лимита для будущих рассылок.
      "capping_avoid": true             // необязательно. Если установлено значение true, ограничение частоты не будет применяться
                                        //           к этому конкретному письму.
    }]
  }
}

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

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

{
  "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 1234567890
(строка) "N days ago" для операторов EQ, BETWEEN, GTE, LTE

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

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

Теги-списки

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

registerEmail

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

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

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

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

Тело запроса

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

{
  "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`	Device API token для доступа к Device API. Замените `XXXX` вашим актуальным Device API token.

Тело запроса

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

{
  "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`	Device API token для доступа к Device API. Замените `XXXX` вашим актуальным Device API token.

Тело запроса

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

{
  "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-адресом.
  }
}

registerEmailUser

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

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

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

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

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

Тело запроса

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

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

{
  "status_code": 400,
  "status_message": "Request format is not valid."
}

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

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