# Email API

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

<Aside type="caution" title="/createEmailMessage is deprecated">
New integrations should use [Messaging API v2](/developer/api-reference/messaging-api-v2/) — pass `platforms: ["EMAIL"]` and an [`email_payload`](/developer/api-reference/messaging-api-v2/email-payload-reference/) block to `Notify`. See the [migration guide](/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createemailmessage).
</Aside>

## createEmailMessage <Badge text="Deprecated" variant="caution" size="small" />

Creates an email message.

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

### Request body parameters

| Name | Type <div style="width:80px"></div> | Required | Description |
|------|--------|:--------:|-------------|
| auth | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| application | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| notifications | `array` | Yes | JSON array containing email message details. See the **Notifications Parameters** table below. |

#### Notifications parameters  

| Name  | Type <div style="width:50px"></div> | Required | Description |
|------|------|:--------:|-------------|
| send_date | `string` | Yes | Defines when to send the email. Format: `YYYY-MM-DD HH:mm` or `"now"`. |
| preset | `string` | Yes | [Email preset code](/developer/api-reference/api-identifiers/#email-content-code). Copy from the URL bar of the **Email Content Editor** in the Pushwoosh Control Panel. |
| subject | `string` or `object` | No | Subject line of the email. The email will always be in the language of the content. If `subject` does not contain a matching language for `content`, the subject will be empty. |
| content | `string` or `object` | No | The email body content. Can be a string for plain HTML content or an object for localized versions. |
| attachments | `array` | No | The email attachments. Only two attachments are available. Each attachment must not exceed 1MB (base64 encoded). |
| list_unsubscribe | `string` | No | Allow to set custom URL for "Link-Unsubscribe" header. |
| campaign | `string` | No | [Campaign code](/developer/api-reference/api-identifiers/#campaign-code) to associate the email with a specific campaign. |
| ignore_user_timezone | `boolean` | No | If `true`, sends the email immediately, ignoring user timezones. |
| timezone | `string` | No | Sends the email according to the user's timezone. Example: `"America/New_York"`. |
| filter | `string` | No | Sends the email to users matching a [specific filter condition](/developer/api-reference/api-identifiers/#segment--filter-name). |
| devices | `array` | No | List of email addresses (max 1000) to send targeted emails. If used, the message is sent only to these addresses. Ignored if the Application Group is used. |
| use_auto_registration | `boolean` | No | If `true`, automatically registers emails from the `devices` parameter. |
| users | `array` | No | If set, the email message will only be delivered to the specified [User ID](/developer/api-reference/api-identifiers/#user-id)s (registered via /registerEmail call). Not more than 1000 user IDs in an array. If the "devices" parameter is specified,the "users" parameter will be ignored. |
| dynamic_content_placeholders | `object` | No | Placeholders for dynamic content instead of device tag values. |
| conditions | `array` | No | Segmentation conditions using tags. Example: `[["Country", "EQ", "BR"]]`. |
| from | `object` | No | Specify a custom sender name and email, overriding the default in application properties. |
| reply-to | `object` | No | Specify a custom reply-to email, overriding the default in application properties.  |
| bcc | `array` | No | BCC (Blind Carbon Copy): array of email addresses that receive a copy of the email without other recipients seeing them. |
| email_type | `string` | No | Specify the email type: `"marketing"` or `"transactional"`. If omitted, users with `PW_ControlGroup: true` will not receive the message. |
| email_category | `string` | Required when `email_type` is `"marketing"`. | Specify one of the category names configured in the [subscription preference center](/product/messaging-channels/emails/email-preferences/) (e.g. Newsletter, Promotional, Product Updates). |
| transactionId | `string` | No | Unique message identifier to prevent re-sending  in case of network problems. Stored on the side of Pushwoosh for 5 minutes.|
| capping\_days              | `integer`            |    No    | The number of days (max 30) to apply frequency capping per device.   **Note:** Ensure [Global frequency capping](/product/messaging-channels/global-frequency-capping/) is configured in the Control Panel.                                                                                                           |
| capping\_count             | `integer`            |    No    | 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           | `boolean`            |    No    | If set to `true`, this email will not  be counted towards the capping for future emails.                                                                                                        |
| capping\_avoid             | `boolean`            |    No    | If set to `true`, capping will not be applied to this specific email.                                                                                     |
| send\_rate                 | `integer`            |    No    | Limit how many messages can be sent per second across all users. Helps prevent backend overload during high-volume sends.
| send\_rate\_avoid          | `boolean`            |    No    | If set to true, throttling limit will not be applied to this specific email.                                                                          |
### Request example
```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.
    }]
  }
}
```

### Response examples
<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>

### Tag conditions

Each tag condition is an array like `[tagName, operator, operand]` where

* tagName: name of a tag
* operator: "EQ" | "IN" | "NOTEQ" | "NOTIN" | "LTE" | "GTE" | "BETWEEN"
* operand: string | integer | array | date

#### Operand description

* EQ: tag value is equal to operand;
* IN: tag value intersects with operand (operand must always be an array);
* NOTEQ: tag value is not equal to an operand;
* NOTIN: tag value does not intersect with operand (operand must always be an array);
* GTE: tag value is greater than or equal to operand;
* LTE: tag value is less than or equal to operand;
* BETWEEN: tag value is greater than or equal to min operand value but less than or equal to max operand value (operand must always be an array).

#### String tags

Valid operators: EQ, IN, NOTEQ, NOTIN\
Valid operands:

* EQ, NOTEQ: operand must be a string;
* IN, NOTIN: operand must be an array of strings like `["value 1", "value 2", "value N"]`;

#### Integer tags

Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE\
Valid operands:

* EQ, NOTEQ, GTE, LTE: operand must be an integer;
* IN, NOTIN: operand must be an array of integers like `[value 1, value 2, value N]`;
* BETWEEN: operand must be an array of integers like `[min_value, max_value]`.

#### Date tags

Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE\
Valid operands:

* `"YYYY-MM-DD 00:00"` (string)
* unix timestamp `1234567890` (integer)
* `"N days ago"` (string) for operators EQ, BETWEEN, GTE, LTE

#### Boolean tags

Valid operators: EQ\
Valid operands: `0, 1, true, false`

#### List tags

Valid operators: IN\
Valid operands: operand must be an array of strings like `["value 1", "value 2", "value N"]`.

<Aside type="danger">
Remember that “filter” and “conditions” parameters should not be used together.\
Also, both of them **will be ignored**, if the "devices" parameter is used in the same request.
</Aside>

<Aside type="note">
**Country and Language tags**

Language tag value is a lowercase two-letter code according to [ISO-639-1](https://en.wikipedia.org/wiki/List\_of\_ISO\_639-1\_codes)\
Country tag value is an UPPERCASE two-letter code according to [ISO\_3166-2](https://en.wikipedia.org/wiki/ISO\_3166-2)\
For example, to send push a notification to Portuguese-speaking subscribers in Brazil, you will need to specify the following condition: `"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]`
</Aside>

## registerEmail

Registers email address for the app.

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

#### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |


#### Request body

| Name                                          | Type    | Description                                                                                         |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| application\* | string  | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                                        |
| email\*       | string  | Email address.                                                                                      |
| language                                      | string  | Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard. |
| userId                                        | string  | [User ID](/developer/api-reference/api-identifiers/#user-id) to associate with the email address.                                                        |
| tz\_offset                                    | integer | Timezone offset in seconds.                                                                         |
| tags                                          | object  | Tag values to assign to the device registered.                                                      |

<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="Example"
{
  "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
    }
  }
}
```

#### Response codes

The public API returns the outcome in `status_code`. Use the table below to decide whether a failed call should be retried.

| `status_code` | Meaning | Retry? |
| ------------- | ------- | ------ |
| `200` | Success — the email address is registered. | No — done. |
| `210` | Argument/validation error — the request was understood but rejected (blacklisted address, invalid or disposable email, wrong platform for the account's plan). See [210 error messages](#210-error-messages) below. | **No** — the same request returns the same `210`. Log the address and skip it. |
| `400` | Malformed request — invalid JSON or a missing required field. | No — fix the request, don't repeat it. |
| `403` | Forbidden — invalid or restricted Device API token. | No — fix authorization. |
| `500` | Internal server error — temporary infrastructure issue or timeout. | **Yes**, with exponential backoff — the only transient case. |

<Aside type="tip">
Retry only `500` responses, using exponential backoff — it's the only transient case. A `210`, `400`, or `403` is final: the server understood your request and rejected it, so repeating it unchanged returns the same result. Log the address (for `210`) or fix the request/token (for `400`/`403`) instead.
</Aside>

#### 210 error messages

A `210` response carries the specific reason in `status_message`.

| `status_message` | Meaning |
| ---------------- | ------- |
| `this hwid (email) is blacklisted` | The address is on the suppression list after a permanent (hard) bounce and won't be re-registered. |
| `hwid (email) is invalid` / `has invalid semantic` | The address fails validation. |
| `hwid (email) is empty` | No address was provided. |
| `hwid (email) has invalid count of parts` | Missing or extra `@`. |
| `hwid (email) has invalid local part` | The part before `@` is invalid. |
| `hwid (email) has invalid domain part` | The domain part is invalid. |
| `hwid (email) has disposable domain` | The address uses a disposable/temporary email domain (e.g. 10minutemail). |
| `hwid is not valid` | The `hwid` itself is malformed. |
| `only email platform allowed for Email Only subscription` | The account is on an Email Only plan and can't register non-email devices. |

<Aside type="note">
Only **permanent (hard) bounces** add an address to the blacklist. Soft bounces and spam complaints do **not** block `registerEmail` — only `this hwid (email) is blacklisted` reflects suppression.
</Aside>

## deleteEmail

Removes email address from your user base.

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

#### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |


#### Request body

| Name        | Type   | Description                                   |
| ----------- | ------ | --------------------------------------------- |
| application | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                 |
| email       | string | Email address used in [`/registerEmail`](/developer/api-reference/email-api/#registeremail) request. |

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

```json title="Example"
{
  "request": {
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}
```

## setEmailTags

Sets tag values for the email address.

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

#### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |

#### Request body

| Name        | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| application | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                   |
| email       | string | Email address.                                                |
| tags        | object | JSON object of tags to set, send 'null' to remove the value.  |
| userId      | string | [User ID](/developer/api-reference/api-identifiers/#user-id) associated with the email address.                    |

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

```json title="Example"
{
  "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">
For other device types will be returned 200 OK, though tags won't be saved.
</Aside>

<Aside type="caution">
Please avoid setting more than 50 tag values in a single `/setEmailTags` request.
</Aside>

## registerEmailUser

Associates an external [User ID](/developer/api-reference/api-identifiers/#user-id) with a specified email address.

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



<Aside type="note">
Please note that this method **does not register an email address** in your user base; it should be used only for assigning user IDs to email addresses that have been registered already by `/registerEmail` request.
</Aside>

Can be used in `/createEmailMessage` API call (the 'users' parameter).

#### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |


#### Request body

| Name                                          | Type    | Description                                    |
| --------------------------------------------- | ------- | ---------------------------------------------- |
| application\* | string  | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                   |
| email\*       | string  | Email address.                                 |
| userId\*      | string  | [User ID](/developer/api-reference/api-identifiers/#user-id) to associate with the email address.   |
| tz\_offset                                    | integer | Timezone offset in seconds.                    |

<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="Example"
{
  "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">
 To retrieve data on soft bounces, hard bounces, and email complaints, including the date, email address, and reason for each bounce, use the [BouncedEmails](/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails) method.
</Aside>