# Email API

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

<Aside type="caution" title="/createEmailMessage 已弃用">
新的集成应使用 [Messaging API v2](/zh/developer/api-reference/messaging-api-v2/) — 将 `platforms: ["EMAIL"]` 和一个 [`email_payload`](/zh/developer/api-reference/messaging-api-v2/email-payload-reference/) 块传递给 `Notify`。请参阅[迁移指南](/zh/developer/api-reference/messaging-api-v2/migration-from-v1/#from-createemailmessage)。
</Aside>

## createEmailMessage <Badge text="已弃用" variant="caution" size="small" />

创建一封电子邮件消息。

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

### 请求正文参数

| 名称 | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|------|--------|:--------:|-------------|
| auth | `string` | 是 | 来自 Pushwoosh Control Panel 的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| application | `string` | 是 | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| notifications | `array` | 是 | 包含电子邮件消息详情的 JSON 数组。请参阅下方的 **Notifications Parameters** 表格。 |

#### Notifications 参数

| 名称 | 类型 <div style="width:50px"></div> | 必需 | 描述 |
|------|------|:--------:|-------------|
| send_date | `string` | 是 | 定义发送电子邮件的时间。格式：`YYYY-MM-DD HH:mm` 或 `"now"`。 |
| preset | `string` | 是 | [Email preset code](/zh/developer/api-reference/api-identifiers/#email-content-code)。从 Pushwoosh Control Panel 中的 **Email Content Editor** 的 URL 栏复制。 |
| subject | `string` 或 `object` | 否 | 电子邮件的主题行。电子邮件将始终使用内容的语言。如果 `subject` 不包含与 `content` 匹配的语言，则主题将为空。 |
| content | `string` 或 `object` | 否 | 电子邮件正文内容。可以是纯 HTML 内容的字符串，也可以是本地化版本的对象。 |
| attachments | `array` | 否 | 电子邮件附件。仅支持两个附件。每个附件（base64 编码后）不得超过 1MB。 |
| list_unsubscribe | `string` | 否 | 允许为 "Link-Unsubscribe" 标头设置自定义 URL。 |
| campaign | `string` | 否 | [Campaign code](/zh/developer/api-reference/api-identifiers/#campaign-code)，用于将电子邮件与特定营销活动关联。 |
| ignore_user_timezone | `boolean` | 否 | 如果为 `true`，则立即发送电子邮件，忽略用户时区。 |
| timezone | `string` | 否 | 根据用户的时区发送电子邮件。示例：`"America/New_York"`。 |
| filter | `string` | 否 | 将电子邮件发送给符合[特定筛选条件](/zh/developer/api-reference/api-identifiers/#segment--filter-name)的用户。 |
| devices | `array` | 否 | 用于发送定向电子邮件的电子邮件地址列表（最多 1000 个）。如果使用此参数，消息将仅发送给这些地址。如果使用 Application Group，则此参数将被忽略。 |
| use_auto_registration | `boolean` | 否 | 如果为 `true`，则自动注册 `devices` 参数中的电子邮件。 |
| users | `array` | 否 | 如果设置，电子邮件消息将仅发送给指定的 [User ID](/zh/developer/api-reference/api-identifiers/#user-id)（通过 /registerEmail 调用注册）。数组中不超过 1000 个 User ID。如果指定了 "devices" 参数，则 "users" 参数将被忽略。 |
| dynamic_content_placeholders | `object` | 否 | 用于动态内容的占位符，以替代设备标签值。 |
| conditions | `array` | 否 | 使用标签的细分条件。示例：`[["Country", "EQ", "BR"]]`。 |
| from | `object` | 否 | 指定自定义的发件人姓名和电子邮件，覆盖应用程序属性中的默认设置。 |
| reply-to | `object` | 否 | 指定自定义的回复邮箱，覆盖应用程序属性中的默认设置。 |
| bcc | `array` | 否 | BCC (Blind Carbon Copy)：接收电子邮件副本的电子邮件地址数组，其他收件人看不到他们。 |
| email_type | `string` | 否 | 指定电子邮件类型：`"marketing"` 或 `"transactional"`。如果省略，`PW_ControlGroup: true` 的用户将不会收到该消息。 |
| email_category | `string` | 当 `email_type` 为 `"marketing"` 时必需。 | 指定在[订阅偏好中心](/zh/product/messaging-channels/emails/email-preferences/)中配置的类别名称之一（例如 Newsletter、Promotional、Product Updates）。 |
| transactionId | `string` | 否 | 唯一的消息标识符，用于在网络问题情况下防止重复发送。在 Pushwoosh 端存储 5 分钟。|
| capping\_days | `integer` | 否 | 对每个设备应用频率上限的天数（最多 30 天）。**注意：** 确保在 Control Panel 中配置了[全局频率上限](/zh/product/messaging-channels/global-frequency-capping/)。 |
| capping\_count | `integer` | 否 | 在 `capping_days` 周期内，可以从特定应用发送到特定设备的最大电子邮件数量。如果创建的消息超出了设备的 `capping_count` 限制，则不会发送给该设备。 |
| capping\_exclude | `boolean` | 否 | 如果设置为 `true`，则此电子邮件将不计入未来电子邮件的频率上限。 |
| capping\_avoid | `boolean` | 否 | 如果设置为 `true`，则频率上限将不适用于此特定电子邮件。 |
| send\_rate | `integer` | 否 | 限制每秒可以向所有用户发送的消息数量。有助于在高发送量期间防止后端过载。 |
| send\_rate\_avoid | `boolean` | 否 | 如果设置为 true，则节流限制将不适用于此特定电子邮件。 |
### 请求示例
```json
{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // 必需。来自 Pushwoosh Control Panel 的 API 访问令牌
    "application": "APPLICATION_CODE",  // 必需。Pushwoosh application code。
    "notifications": [{
      "send_date": "now",               // 必需。YYYY-MM-DD HH:mm 或 'now'
      "preset": "ERXXX-32XXX",          // 必需。从 Pushwoosh Control Panel 的
                                        //           Email Content editor 页面的 URL 栏复制 Email preset code。
      "subject": {                      // 可选。电子邮件消息主题行。
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // 可选。电子邮件正文内容。
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // 可选。电子邮件附件
        "name": "image.png",            //           "name" - 文件名
        "content": "iVBANA...AFTkuQmwC" //           "content" - 文件的 base64 编码内容
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // 可选。允许为 "Link-Unsubscribe" 标头设置自定义 URL
      "campaign": "CAMPAIGN_CODE",      // 可选。要将此电子邮件消息分配给特定营销活动，
                                        //           请在此处添加营销活动代码。
      "ignore_user_timezone": true,     // 可选。
      "timezone": "America/New_York",   // 可选。指定根据用户设备上设置的时区
                                        //           发送消息。
      "filter": "FILTER_NAME",          // 可选。将消息发送给满足筛选条件的特定用户。
      "devices": [                      // 可选。指定要发送定向电子邮件消息的电子邮件地址。
        "email_address1",               //           数组中不超过 1000 个地址。
        "email_address2"                //           如果设置，消息将仅发送给列表中的地址。
      ],                                //           如果使用 Application Group，则此参数将被忽略。
      "use_auto_registration": true,    // 可选。自动注册在 "devices" 参数中指定的电子邮件
      "users": [                        // 可选。如果设置，电子邮件消息将仅发送给
        "userId1",                      //           指定的用户 ID（通过 /registerEmail 调用注册）。
        "userId2"                       //           数组中不超过 1000 个用户 ID。
      ],                                //           如果指定了 "devices" 参数，
                                        //           则 "users" 参数将被忽略。
      "dynamic_content_placeholders": { // 可选。用于动态内容的占位符，以替代设备标签值。
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // 可选。细分条件，请参阅下面的备注。
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // 可选。指定发件人姓名和发件人电子邮件地址
        "name": "alias from",           //           以替换应用程序属性中设置的
        "email": "from-email@email.com" //           默认 "From name" 和 "From email"。
      },
      "reply-to": {                     // 可选。指定一个电子邮件地址以替换
        "name": "alias reply to ",      //           应用程序属性中设置的默认 "Reply to"。
        "email": "reply-to@email.com"
      },
      "bcc": [                          // 可选。BCC：接收副本而其他收件人看不到的电子邮件地址数组。
        "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 分钟。
      // 频率上限参数。确保在 Control Panel 中配置了全局频率上限。
      // 频率上限不适用于事务性消息。
      // 在所有其他情况下，包括省略 "email_type" 的情况，频率上限均适用。
      "capping_days": 30,               // 可选。频率上限的天数（最多 30 天）
      "capping_count": 10,              // 可选。在 'capping_days' 周期内，可以从特定应用
                                        //           发送到特定设备的最大电子邮件数量。
                                        //           如果创建的消息超出了设备的 'capping_count' 限制，
                                        //           则不会发送给该设备。
      "capping_exclude": true,          // 可选。如果设置为 true，此电子邮件将不计入
                                        //           未来电子邮件的频率上限。
      "capping_avoid": true,            // 可选。如果设置为 true，频率上限将不适用于
                                        //           此特定电子邮件。
      "send_rate": 100,                 // 可选。节流限制。
                                        //           限制每秒可以向所有用户发送的消息数量。
                                        //           有助于在高发送量期间防止后端过载。
      "send_rate_avoid": true,          // 可选。如果设置为 true，节流限制将不适用于
                                        //           此特定电子邮件。
    }]
  }
}
```

### 响应示例
<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"` (string)
* unix 时间戳 `1234567890` (integer)
* `"N days ago"` (string)，用于运算符 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">
**国家和语言标签**

语言标签值是根据 [ISO-639-1](https://en.wikipedia.org/wiki/List\_of\_ISO\_639-1\_codes) 的小写双字母代码\
国家标签值是根据 [ISO\_3166-2](https://en.wikipedia.org/wiki/ISO\_3166-2) 的大写双字母代码\
例如，要向巴西的葡萄牙语订阅者发送推送通知，您需要指定以下条件：`"conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]`
</Aside>

## registerEmail

为应用注册电子邮件地址。

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

#### 请求头

| 名称 | 必需 | 值 | 描述 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 是 | Token `XXXX` | 用于访问 Device API 的 [API Device Token](/zh/developer/api-reference/api-access-token/#device-api-token)。将 `XXXX` 替换为您的实际 Device API token。 |


#### 请求正文

| 名称 | 类型 | 描述 |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| application\* | string | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| email\* | string | 电子邮件地址。 |
| language | string | 设备的语言区域设置。必须是符合 ISO-639-1 标准的小写双字母代码。 |
| userId | string | 要与电子邮件地址关联的 [User ID](/zh/developer/api-reference/api-identifiers/#user-id)。 |
| 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",   // 必需。Pushwoosh application code。
    "email":"email@domain.com",          // 必需。要注册的电子邮件地址。
    "language": "en",                    // 可选。语言区域设置。
    "userId": "userId",                  // 可选。要与电子邮件地址关联的用户 ID。
    "tz_offset": 3600,                   // 可选。时区偏移量（秒）。
    "tags": {                            // 可选。为已注册设备设置的标签值。
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // 为列表类型的标签设置值列表
       "DateTag": "2024-10-02 22:11",    // 注意时间应为 UTC
       "BooleanTag": true                // 有效值为：true, false
    }
  }
}
```

#### 响应代码

公共 API 在 `status_code` 中返回结果。使用下表来决定失败的调用是否应重试。

| `status_code` | 含义 | 重试？ |
| ------------- | ------- | ------ |
| `200` | 成功 — 电子邮件地址已注册。 | 否 — 完成。 |
| `210` | 参数/验证错误 — 请求被理解但被拒绝（地址被列入黑名单、无效或一次性电子邮件、账户计划的平台错误）。请参阅下方的 [210 错误消息](#210-error-messages)。 | **否** — 相同的请求将返回相同的 `210`。记录该地址并跳过它。 |
| `400` | 格式错误的请求 — 无效的 JSON 或缺少必需字段。 | 否 — 修复请求，不要重复。 |
| `403` | 禁止 — 无效或受限的 Device API token。 | 否 — 修复授权。 |
| `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` | 地址使用一次性/临时电子邮件域名（例如 10minutemail）。 |
| `hwid is not valid` | `hwid` 本身格式不正确。 |
| `only email platform allowed for Email Only subscription` | 该账户是仅限电子邮件的计划，无法注册非电子邮件设备。 |

<Aside type="note">
只有**永久（硬）退回**才会将地址添加到黑名单。软退回和垃圾邮件投诉**不会**阻止 `registerEmail` — 只有 `this hwid (email) is blacklisted` 反映了抑制状态。
</Aside>

## deleteEmail

从您的用户群中删除电子邮件地址。

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

#### 请求头

| 名称 | 必需 | 值 | 描述 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 是 | Token `XXXX` | 用于访问 Device API 的 [API Device Token](/zh/developer/api-reference/api-access-token/#device-api-token)。将 `XXXX` 替换为您的实际 Device API token。 |


#### 请求正文

| 名称 | 类型 | 描述 |
| ----------- | ------ | --------------------------------------------- |
| application | string | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| email | string | 在 [`/registerEmail`](/zh/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",  // 必需。Pushwoosh application code
    "email": "email@domain.com"         // 必需。要从应用订阅者中删除的电子邮件。
  }
}
```

## setEmailTags

为电子邮件地址设置标签值。

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

#### 请求头

| 名称 | 必需 | 值 | 描述 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 是 | Token `XXXX` | 用于访问 Device API 的 [API Device Token](/zh/developer/api-reference/api-access-token/#device-api-token)。将 `XXXX` 替换为您的实际 Device API token。 |

#### 请求正文

| 名称 | 类型 | 描述 |
| ----------- | ------ | ------------------------------------------------------------- |
| application | string | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| email | string | 电子邮件地址。 |
| tags | object | 要设置的标签的 JSON 对象，发送 'null' 以删除值。 |
| userId | string | 与电子邮件地址关联的 [User ID](/zh/developer/api-reference/api-identifiers/#user-id)。 |

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

```json title="示例"
{
  "request": {
    "email": "email@domain.com",                  // 必需。要设置标签的电子邮件地址。
    "application": "APPLICATION_CODE",            // 必需。Pushwoosh application code。
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // UTC 时间
      "BooleanTag": true                          // 有效值为：true, false
    },
    "userId": "userId"                            // 可选。与电子邮件地址关联的用户 ID。
  }
}
```

<Aside type="note">
对于其他设备类型，将返回 200 OK，但标签不会被保存。
</Aside>

<Aside type="caution">
请避免在单个 `/setEmailTags` 请求中设置超过 50 个标签值。
</Aside>

## registerEmailUser

将外部 [User ID](/zh/developer/api-reference/api-identifiers/#user-id) 与指定的电子邮件地址关联。

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



<Aside type="note">
请注意，此方法**不会在您的用户群中注册电子邮件地址**；它仅应用于将用户 ID 分配给已通过 `/registerEmail` 请求注册的电子邮件地址。
</Aside>

可以在 `/createEmailMessage` API 调用中使用（'users' 参数）。

#### 请求头

| 名称 | 必需 | 值 | 描述 |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | 是 | Token `XXXX` | 用于访问 Device API 的 [API Device Token](/zh/developer/api-reference/api-access-token/#device-api-token)。将 `XXXX` 替换为您的实际 Device API token。 |


#### 请求正文

| 名称 | 类型 | 描述 |
| --------------------------------------------- | ------- | ---------------------------------------------- |
| application\* | string | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| email\* | string | 电子邮件地址。 |
| userId\* | string | 要与电子邮件地址关联的 [User ID](/zh/developer/api-reference/api-identifiers/#user-id)。 |
| 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", // 必需。Pushwoosh application code。
    "email": "email@domain.com",       // 必需。用户电子邮件地址。
    "userId": "userId",                // 必需。要与电子邮件地址关联的用户 ID。
    "tz_offset": 3600                  // 可选。时区偏移量（秒）。
  }
}
```

<Aside type="note">
要检索有关软退回、硬退回和电子邮件投诉的数据，包括每次退回的日期、电子邮件地址和原因，请使用 [BouncedEmails](/zh/developer/api-reference/statistics-api/message-statistics-api/#bouncedemails) 方法。
</Aside>