Email API

createEmailMessage 已弃用

创建一封电子邮件消息。

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

请求体参数

名称	类型	必需	描述
auth	`string`	是	Pushwoosh 控制面板中的 API 访问令牌。
application	`string`	是	Pushwoosh 应用程序代码
notifications	`array`	是	包含电子邮件消息详情的 JSON 数组。请参阅下方的 Notifications 参数表。

Notifications 参数

名称	类型	必需	描述
send_date	`string`	是	定义发送电子邮件的时间。格式：`YYYY-MM-DD HH:mm` 或 `"now"`。
preset	`string`	是	电子邮件预设代码。从 Pushwoosh 控制面板中电子邮件内容编辑器的 URL 栏复制。
subject	`string` 或 `object`	否	电子邮件的主题行。电子邮件将始终使用内容的语言。如果 `subject` 不包含与 `content` 匹配的语言，则主题将为空。
content	`string` 或 `object`	否	电子邮件正文内容。可以是纯 HTML 内容的字符串，也可以是本地化版本的对象。
attachments	`array`	否	电子邮件附件。仅支持两个附件。每个附件（base64 编码后）不得超过 1MB。
list_unsubscribe	`string`	否	允许为 “Link-Unsubscribe” 标头设置自定义 URL。
campaign	`string`	否	活动代码，用于将电子邮件与特定活动关联。
ignore_user_timezone	`boolean`	否	如果为 `true`，则立即发送电子邮件，忽略用户时区。
timezone	`string`	否	根据用户的时区发送电子邮件。示例：`"America/New_York"`。
filter	`string`	否	将电子邮件发送给匹配特定筛选条件的用户。
devices	`array`	否	目标电子邮件地址列表（最多 1000 个）。如果使用，消息仅发送到这些地址。如果使用应用程序组，则此参数将被忽略。
use_auto_registration	`boolean`	否	如果为 `true`，则自动注册 `devices` 参数中的电子邮件。
users	`array`	否	如果设置，电子邮件消息将仅发送给指定的 User ID（通过 /registerEmail 调用注册）。数组中不超过 1000 个用户 ID。如果指定了 “devices” 参数，则 “users” 参数将被忽略。
dynamic_content_placeholders	`object`	否	用于动态内容的占位符，以替代设备标签值。
conditions	`array`	否	使用标签的细分条件。示例：`[["Country", "EQ", "BR"]]`。
from	`object`	否	指定自定义的发件人姓名和电子邮件，覆盖应用程序属性中的默认设置。
reply-to	`object`	否	指定自定义的回复邮箱，覆盖应用程序属性中的默认设置。
bcc	`array`	否	BCC (密送)：接收电子邮件副本的电子邮件地址数组，其他收件人不会看到他们。
email_type	`string`	否	指定电子邮件类型：`"marketing"` 或 `"transactional"`。如果省略，消息将被视为事务性消息，并发送给所有人，包括控制组。营销消息不会发送给控制组成员。
email_category	`string`	当 `email_type` 为 `"marketing"` 时必需。	指定在订阅偏好中心中配置的类别名称之一（例如 Newsletter、Promotional、Product Updates）。
transactionId	`string`	否	唯一的消息标识符，用于在网络问题情况下防止重复发送。在 Pushwoosh 端存储 5 分钟。
capping_days	`integer`	否	对每个设备应用频率上限的天数（最多 30 天）。注意：确保在控制面板中配置了全局频率上限。
capping_count	`integer`	否	在 `capping_days` 期间内，可以从特定应用发送到特定设备的最大电子邮件数量。如果创建的消息超出了设备的 `capping_count` 限制，则不会发送到该设备。
capping_exclude	`boolean`	否	如果设置为 `true`，此电子邮件将不计入未来电子邮件的频率上限。
capping_avoid	`boolean`	否	如果设置为 `true`，频率上限将不适用于此特定电子邮件。
send_rate	`integer`	否	限制每秒可以向所有用户发送的消息数量。有助于在高流量发送期间防止后端过载。
send_rate_avoid	`boolean`	否	如果设置为 true，节流限制将不适用于此特定电子邮件。

请求示例

{
  "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, treated as transactional: delivered to everyone.
                                        // Marketing messages are not delivered to control group members.
      "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.
    }]
  }
}

响应示例

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

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

标签条件

每个标签条件都是一个类似 [tagName, operator, operand] 的数组，其中

tagName：标签的名称
operator：“EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
operand：字符串 | 整数 | 数组 | 日期

操作数描述

EQ：标签值等于操作数；
IN：标签值与操作数相交（操作数必须始终为数组）；
NOTEQ：标签值不等于操作数；
NOTIN：标签值不与操作数相交（操作数必须始终为数组）；
GTE：标签值大于或等于操作数；
LTE：标签值小于或等于操作数；
BETWEEN：标签值大于或等于最小操作数值，但小于或等于最大操作数值（操作数必须始终为数组）。

字符串标签

有效运算符：EQ, IN, NOTEQ, NOTIN
有效操作数：

EQ, NOTEQ：操作数必须是字符串；
IN, NOTIN：操作数必须是字符串数组，如 ["value 1", "value 2", "value N"]；

整数标签

有效运算符：EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
有效操作数：

EQ, NOTEQ, GTE, LTE：操作数必须是整数；
IN, NOTIN：操作数必须是整数数组，如 [value 1, value 2, value N]；
BETWEEN：操作数必须是整数数组，如 [min_value, max_value]。

日期标签

有效运算符：EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
有效操作数：

"YYYY-MM-DD 00:00" (字符串)
unix 时间戳 1234567890 (整数)
"N days ago" (字符串) 适用于 EQ, BETWEEN, GTE, LTE 运算符

布尔标签

有效运算符：EQ
有效操作数：0, 1, true, false

列表标签

有效运算符：IN
有效操作数：操作数必须是字符串数组，如 ["value 1", "value 2", "value N"]。

registerEmail

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

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

请求标头

名称	必需	值	描述
Authorization	是	Token `XXXX`	用于访问设备 API 的 API 设备令牌。将 `XXXX` 替换为您的实际设备 API 令牌。

请求体

名称	类型	描述
application*	string	Pushwoosh 应用程序代码
email*	string	电子邮件地址。
language	string	设备的语言区域设置。必须是符合 ISO-639-1 标准的小写双字母代码。
userId	string	与电子邮件地址关联的 User ID。
tz_offset	integer	时区偏移量（秒）。
tags	object	要分配给已注册设备的标签值。

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

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

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

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

{
  "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`	成功 — 电子邮件地址已注册。	否 — 已完成。
`210`	参数/验证错误 — 请求被理解但被拒绝（地址被列入黑名单、电子邮件无效或一次性、账户计划的平台错误）。请参阅下方的 210 错误消息。	否 — 相同的请求将返回相同的 `210`。记录该地址并跳过它。
`400`	格式错误的请求 — 无效的 JSON 或缺少必需字段。	否 — 修复请求，不要重复。
`403`	禁止 — 无效或受限的 Device API 令牌。	否 — 修复授权。
`500`	内部服务器错误 — 临时基础设施问题或超时。	是，采用指数退避 — 唯一的瞬时情况。

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`	该账户为纯电子邮件套餐，无法注册非电子邮件设备。

deleteEmail

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

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

请求标头

名称	必需	值	描述
Authorization	是	Token `XXXX`	用于访问设备 API 的 API 设备令牌。将 `XXXX` 替换为您的实际设备 API 令牌。

请求体

名称	类型	描述
application	string	Pushwoosh 应用程序代码
email	string	在 `/registerEmail` 请求中使用的电子邮件地址。

{
  "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

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

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

请求标头

名称	必需	值	描述
Authorization	是	Token `XXXX`	用于访问设备 API 的 API 设备令牌。将 `XXXX` 替换为您的实际设备 API 令牌。

请求体

名称	类型	描述
application	string	Pushwoosh 应用程序代码
email	string	电子邮件地址。
tags	object	要设置的标签的 JSON 对象，发送 ‘null’ 以删除值。
userId	string	与电子邮件地址关联的 User ID。

{
  "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.
  }
}

registerEmailUser

将外部 User ID 与指定的电子邮件地址关联。

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

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

请求标头

名称	必需	值	描述
Authorization	是	Token `XXXX`	用于访问设备 API 的 API 设备令牌。将 `XXXX` 替换为您的实际设备 API 令牌。

请求体

名称	类型	描述
application*	string	Pushwoosh 应用程序代码
email*	string	电子邮件地址。
userId*	string	与电子邮件地址关联的 User ID。
tz_offset	integer	时区偏移量（秒）。

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

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

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

{
  "request": {
    "application": "APPLICATION_CODE", // 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.
  }
}