# Email API

import { Badge } from '@astrojs/starlight/components';

<Aside type="caution" title="/createEmailMessage устарел">
В новых интеграциях следует использовать [Messaging API v2](/ru/developer/api-reference/messaging-api-v2/) — передайте `platforms: ["EMAIL"]` и блок [`email_payload`](/ru/developer/api-reference/messaging-api-v2/email-payload-reference/) в `Notify`. См. [руководство по миграции](/ru/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createemailmessage).
</Aside>

## createEmailMessage <Badge text="Устарел" variant="caution" size="small" />

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

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

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

| Имя | Тип <div style="width:80px"></div> | Обязательный | Описание |
|------|--------|:--------:|-------------|
| auth | `string` | Да | [Токен доступа API](/ru/developer/api-reference/api-identifiers/#api-access-token) из Панели управления Pushwoosh. |
| application | `string` | Да | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) |
| notifications | `array` | Да | JSON-массив, содержащий детали email-сообщения. См. таблицу **Параметры Notifications** ниже. |

#### Параметры Notifications

| Имя  | Тип <div style="width:50px"></div> | Обязательный | Описание |
|------|------|:--------:|-------------|
| send_date | `string` | Да | Определяет, когда отправлять email. Формат: `YYYY-MM-DD HH:mm` или `"now"`. |
| preset | `string` | Да | [Код пресета Email](/ru/developer/api-reference/api-identifiers/#email-content-code). Скопируйте из 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` | Нет | [Код кампании](/ru/developer/api-reference/api-identifiers/#campaign-code) для связи email с определенной кампанией. |
| ignore_user_timezone | `boolean` | Нет | Если `true`, отправляет email немедленно, игнорируя часовые пояса пользователей. |
| timezone | `string` | Нет | Отправляет email в соответствии с часовым поясом пользователя. Пример: `"America/New_York"`. |
| filter | `string` | Нет | Отправляет email пользователям, соответствующим [определенному условию фильтра](/ru/developer/api-reference/api-identifiers/#segment--filter-name). |
| devices | `array` | Нет | Список email-адресов (максимум 1000) для отправки целевых email. При использовании сообщение отправляется только на эти адреса. Игнорируется, если используется Группа приложений. |
| use_auto_registration | `boolean` | Нет | Если `true`, автоматически регистрирует email из параметра `devices`. |
| users | `array` | Нет | Если установлено, email-сообщение будет доставлено только указанным [User ID](/ru/developer/api-reference/api-identifiers/#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"`. | Укажите одно из названий категорий, настроенных в [центре управления подписками](/ru/product/messaging-channels/emails/email-preferences/) (например, Newsletter, Promotional, Product Updates). |
| transactionId | `string` | Нет | Уникальный идентификатор сообщения для предотвращения повторной отправки в случае проблем с сетью. Хранится на стороне Pushwoosh в течение 5 минут. |
| capping\_days | `integer` | Нет | Количество дней (максимум 30) для применения ограничения частоты отправки на устройство. **Примечание:** Убедитесь, что [Глобальное ограничение частоты отправки](/ru/product/messaging-channels/global-frequency-capping/) настроено в Панели управления. |
| 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. |

### Пример запроса
```json 
{
  "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.
    }]
  }
}
```

### Примеры ответа
<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>

<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}
```
</TabItem>
</Tabs>

### Условия по тегам

Каждое условие по тегу представляет собой массив вида `[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"]`.

<Aside type="danger">
Помните, что параметры “filter” и “conditions” не должны использоваться вместе.\
Кроме того, оба они **будут проигнорированы**, если в том же запросе используется параметр "devices".
</Aside>

<Aside type="note">
**Теги Country и Language**

Значение тега Language — это двухбуквенный код в нижнем регистре согласно [ISO-639-1](https://en.wikipedia.org/wiki/List\_of\_ISO\_639-1\_codes)\
Значение тега Country — это двухбуквенный код в ВЕРХНЕМ РЕГИСТРЕ согласно [ISO\_3166-2](https://en.wikipedia.org/wiki/ISO\_3166-2)\
Например, чтобы отправить push-уведомление португалоязычным подписчикам в Бразилии, вам нужно будет указать следующее условие: `"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]`
</Aside>

## registerEmail

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

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

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

| Имя | Обязательный | Значение | Описание |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Да | Token `XXXX` | [Токен устройства API](/ru/developer/api-reference/api-access-token/#device-api-token) для доступа к Device API. Замените `XXXX` вашим фактическим токеном устройства API. |


#### Тело запроса

| Имя | Тип | Описание |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| application\* | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) |
| email\* | string | Email-адрес. |
| language | string | Языковая локаль устройства. Должен быть двухбуквенным кодом в нижнем регистре согласно стандарту ISO-639-1. |
| userId | string | [User ID](/ru/developer/api-reference/api-identifiers/#user-id) для связи с email-адресом. |
| tz\_offset | integer | Смещение часового пояса в секундах. |
| tags | object | Значения тегов для присвоения зарегистрированному устройству. |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
<TabItem label="210">
```json
{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}
```
</TabItem>
<TabItem label="400">
```json
{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}
```
</TabItem>
<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}
```
</TabItem>
<TabItem label="500">
```json
{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="Пример"
{
  "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-error-messages) ниже. | **Нет** — тот же запрос вернет тот же `210`. Запишите адрес и пропустите его. |
| `400` | Неверно сформированный запрос — недействительный JSON или отсутствует обязательное поле. | Нет — исправьте запрос, не повторяйте его. |
| `403` | Запрещено — недействительный или ограниченный токен устройства API. | Нет — исправьте авторизацию. |
| `500` | Внутренняя ошибка сервера — временная проблема с инфраструктурой или тайм-аут. | **Да**, с экспоненциальной задержкой — единственный временный случай. |

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

#### Сообщения об ошибке 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 устройства. |

<Aside type="note">
Только **постоянные (жесткие) возвраты** добавляют адрес в черный список. Мягкие возвраты и жалобы на спам **не** блокируют `registerEmail` — только `this hwid (email) is blacklisted` отражает подавление.
</Aside>

## deleteEmail

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

`POST` `https://api.pushwoosh.com/json/1.3/deleteEmail`

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

| Имя | Обязательный | Значение | Описание |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Да | Token `XXXX` | [Токен устройства API](/ru/developer/api-reference/api-access-token/#device-api-token) для доступа к Device API. Замените `XXXX` вашим фактическим токеном устройства API. |


#### Тело запроса

| Имя | Тип | Описание |
| ----------- | ------ | --------------------------------------------- |
| application | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) |
| email | string | Email-адрес, использованный в запросе [`/registerEmail`](/ru/developer/api-reference/email-api/#registeremail). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="Пример"
{
  "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](/ru/developer/api-reference/api-access-token/#device-api-token) для доступа к Device API. Замените `XXXX` вашим фактическим токеном устройства API. |

#### Тело запроса

| Имя | Тип | Описание |
| ----------- | ------ | ------------------------------------------------------------- |
| application | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) |
| email | string | Email-адрес. |
| tags | object | JSON-объект тегов для установки, отправьте 'null' для удаления значения. |
| userId | string | [User ID](/ru/developer/api-reference/api-identifiers/#user-id), связанный с email-адресом. |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}
```
</TabItem>
</Tabs>

```json title="Пример"
{
  "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.
  }
}
```

<Aside type="note">
Для других типов устройств будет возвращен 200 OK, хотя теги не будут сохранены.
</Aside>

<Aside type="caution">
Пожалуйста, избегайте установки более 50 значений тегов в одном запросе `/setEmailTags`.
</Aside>

## registerEmailUser

Связывает внешний [User ID](/ru/developer/api-reference/api-identifiers/#user-id) с указанным email-адресом.

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



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

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

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

| Имя | Обязательный | Значение | Описание |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Да | Token `XXXX` | [Токен устройства API](/ru/developer/api-reference/api-access-token/#device-api-token) для доступа к Device API. Замените `XXXX` вашим фактическим токеном устройства API. |


#### Тело запроса

| Имя | Тип | Описание |
| --------------------------------------------- | ------- | ---------------------------------------------- |
| application\* | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) |
| email\* | string | Email-адрес. |
| userId\* | string | [User ID](/ru/developer/api-reference/api-identifiers/#user-id) для связи с email-адресом. |
| tz\_offset | integer | Смещение часового пояса в секундах. |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>

<TabItem label="400">
```json
{
  "status_code": 400,
  "status_message": "Request format is not valid."
}
```
</TabItem>

<TabItem label="403">
```json
{
  "status_code": 403,
  "status_message": "Forbidden."
}
```
</TabItem>
</Tabs>

```json title="Пример"
{
  "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.
  }
}
```

<Aside type="note">
Чтобы получить данные о мягких возвратах, жестких возвратах и жалобах на email, включая дату, email-адрес и причину каждого возврата, используйте метод [BouncedEmails](/ru/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails).
</Aside>