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-сообщения. См. таблицу Параметры Notifications ниже.

Параметры Notifications

Имя	Тип	Обязательный	Описание
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, невидимую для других получателей.
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) для применения ограничения частоты отправки на устройство. Примечание: Убедитесь, что Глобальное ограничение частоты отправки настроено в Панели управления.
capping_count	integer	Нет	Максимальное количество email, которое может быть отправлено из определенного приложения на конкретное устройство в течение периода capping_days. Если созданное сообщение превышает лимит capping_count для устройства, оно не будет отправлено на это устройство.
capping_exclude	boolean	Нет	Если установлено значение true, этот email не будет учитываться при ограничении частоты для будущих email.
capping_avoid	boolean	Нет	Если установлено значение true, ограничение частоты не будет применяться к этому конкретному email.
send_rate	integer	Нет	Ограничение количества сообщений, которые могут быть отправлены в секунду всем пользователям. Помогает предотвратить перегрузку бэкенда при массовых отправках.
send_rate_avoid	boolean	Нет	Если установлено значение true, ограничение скорости отправки не будет применяться к этому конкретному email.

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

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // required. YYYY-MM-DD HH:mm  OR 'now'
      "preset": "ERXXX-32XXX",          // required. Copy Email preset code from the URL bar of
                                        //           the Email Content editor page in Pushwoosh Control Panel.
      "subject": {                      // optional. Email message subject line.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Email body content.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. Email attachments
        "name": "image.png",            //           "name" - file name
        "content": "iVBANA...AFTkuQmwC" //           "content" - base64 encoded content of the file
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Allow to set custom URL for "Link-Unsubscribe" header
      "campaign": "CAMPAIGN_CODE",      // optional. To assign this email message to a particular campaign,
                                        //           add a campaign code here.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Specify to send the message according to
                                        //           timezone set on user's device.
      "filter": "FILTER_NAME",          // optional. Send the message to specific users meeting filter conditions.
      "devices": [                      // optional. Specify email addresses to send targeted email messages.
        "email_address1",               //           Not more than 1000 addresses in an array.
        "email_address2"                //           If set, the message will only be sent to the addresses on
      ],                                //           the list. Ignored if the Application Group is used.
      "use_auto_registration": true,    // optional. Automatically register emails specified in "devices" parameter
      "users": [                        // optional. If set, the email message will only be delivered to the
        "userId1",                      //           specified user IDs (registered via /registerEmail call).
        "userId2"                       //           Not more than 1000 user IDs in an array.
      ],                                //           If the "devices" parameter is specified,
                                        //           the "users" parameter will be ignored.
      "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // optional. Segmentation conditions, see remark below.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // optional. Specify a sender name and sender email address
        "name": "alias from",           //           to replace the default "From name" and "From email"
        "email": "from-email@email.com" //           set up in application properties.
      },
      "reply-to": {                     // optional. Specify an email address to replace the
        "name": "alias reply to ",      //           default "Reply to" set up in application properties.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // optional. BCC: array of email addresses that receive a copy without other recipients seeing them.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // optional. "marketing" or "transactional".
                                        // If omitted, users with PW_ControlGroup: true will not receive the message.
      "email_category": "category name",// required when email_type is "marketing". Category name.
      "transactionId": "unique UUID",   // optional. Unique message identifier to prevent re-sending
                                        //           in case of network problems. Stored on the side
                                        //           of Pushwoosh for 5 minutes.
      // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel.
      // Frequency capping does not apply to transactional messages.
      // In all other cases, including omitted "email_type", frequency capping applies.
      "capping_days": 30,               // optional. Amount of days for frequency capping (max 30 days)
      "capping_count": 10,              // optional. The max number of emails that can be sent from a
                                        //           specific app to a particular device within a 'capping_days'
                                        //           period. In case the message created exceeds the
                                        //           'capping_count' limit for a device, it won't
                                        //           be sent to that device.
      "capping_exclude": true,          // optional. If set to true, this email will not
                                        //           be counted towards the capping for future emails.
      "capping_avoid": true,            // optional. If set to true, capping will not be applied to
                                        //           this specific email.
      "send_rate": 100,                 // optional. Throttling limit.
                                        //           Limit how many messages can be sent per second across all users.
                                        //           Helps prevent backend overload during high-volume sends.
      "send_rate_avoid": true,          // optional. If set to true, throttling limit will not be applied to
                                        //           this specific email.
    }]
  }
}

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

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”.

Примечание

Теги 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	Да	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
}

210

{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}

400

{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}

403

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

500

{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}

Пример

{
  "request": {
    "application": "APPLICATION_CODE",   // required. Pushwoosh application code.
    "email":"email@domain.com",          // required. Email address to be registered.
    "language": "en",                    // optional. Language locale.
    "userId": "userId",                  // optional. User ID to associate with the email address.
    "tz_offset": 3600,                   // optional. Timezone offset in seconds.
    "tags": {                            // optional. Tag values to set for the device registered.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
       "DateTag": "2024-10-02 22:11",    // note the time should be in UTC
       "BooleanTag": true                // valid values are: true, false
    }
  }
}

Коды ответа

Публичный API возвращает результат в status_code. Используйте таблицу ниже, чтобы решить, следует ли повторять неудачный вызов.

status_code	Значение	Повторять?
200	Успех — email-адрес зарегистрирован.	Нет — выполнено.
210	Ошибка аргумента/валидации — запрос был понят, но отклонен (адрес в черном списке, недействительный или одноразовый email, неправильная платформа для плана аккаунта). См. сообщения об ошибке 210 ниже.	Нет — тот же запрос вернет тот же 210. Запишите адрес и пропустите его.
400	Неверно сформированный запрос — недействительный JSON или отсутствует обязательное поле.	Нет — исправьте запрос, не повторяйте его.
403	Запрещено — недействительный или ограниченный токен устройства API.	Нет — исправьте авторизацию.
500	Внутренняя ошибка сервера — временная проблема с инфраструктурой или тайм-аут.	Да, с экспоненциальной задержкой — единственный временный случай.

Совет

Повторяйте только ответы 500, используя экспоненциальную задержку — это единственный временный случай. Ответ 210, 400 или 403 является окончательным: сервер понял ваш запрос и отклонил его, поэтому повторение без изменений вернет тот же результат. Вместо этого запишите адрес (для 210) или исправьте запрос/токен (для 400/403).

Сообщения об ошибке 210

Ответ 210 содержит конкретную причину в status_message.

status_message	Значение
this hwid (email) is blacklisted	Адрес находится в списке подавления после постоянного (жесткого) возврата и не будет повторно зарегистрирован.
hwid (email) is invalid / has invalid semantic	Адрес не прошел валидацию.
hwid (email) is empty	Адрес не был предоставлен.
hwid (email) has invalid count of parts	Отсутствует или лишний символ @.
hwid (email) has invalid local part	Часть до @ недействительна.
hwid (email) has invalid domain part	Доменная часть недействительна.
hwid (email) has disposable domain	Адрес использует одноразовый/временный домен email (например, 10minutemail).
hwid is not valid	Сам hwid неверно сформирован.
only email platform allowed for Email Only subscription	Аккаунт находится на плане Email Only и не может регистрировать не-email устройства.

Примечание

Только постоянные (жесткие) возвраты добавляют адрес в черный список. Мягкие возвраты и жалобы на спам не блокируют registerEmail — только this hwid (email) is blacklisted отражает подавление.

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",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

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",                  // required. Email address to set tags for.
    "application": "APPLICATION_CODE",            // required. Pushwoosh application code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // time in UTC
      "BooleanTag": true                          // valid values are: true, false
    },
    "userId": "userId"                            // optional. User ID associated with the email address.
  }
}

Примечание

Для других типов устройств будет возвращен 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", // required. Pushwoosh application code.
    "email": "email@domain.com",       // required. User email address.
    "userId": "userId",                // required. User ID to associate with the email address.
    "tz_offset": 3600                  // optional. Timezone offset in seconds.
  }
}

Примечание

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