跳到内容
用户指南支持 请求演示 登录
Pushwoosh.com

邮件 API

createEmailMessage

Anchor link to

创建一封电子邮件。

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

请求体参数

Anchor link to
名称类型
必需描述
authstring是来自 Pushwoosh 控制面板的 API access token。
applicationstring是Pushwoosh application code
notificationsarray是包含电子邮件详细信息的 JSON 数组。请参阅下方的 Notifications 参数 表。

Notifications 参数

Anchor link to
名称类型
必需描述
send_datestring是定义发送邮件的时间。格式：YYYY-MM-DD HH:mm 或 "now"。
presetstring是邮件预设代码。从 Pushwoosh 控制面板的 邮件内容编辑器 的 URL 栏中复制。
subjectstring 或 object否邮件的主题行。邮件将始终使用内容的语言。如果 subject 不包含与 content 匹配的语言，则主题将为空。
contentstring 或 object否邮件正文内容。可以是纯 HTML 内容的字符串，也可以是本地化版本的对象。
attachmentsarray否邮件附件。最多只支持两个附件。每个附件（base64 编码后）不得超过 1MB。
list_unsubscribestring否允许为 “Link-Unsubscribe” 标头设置自定义 URL。
campaignstring否用于将邮件与特定营销活动关联的 Campaign code。
ignore_user_timezoneboolean否如果为 true，则立即发送邮件，忽略用户时区。
timezonestring否根据用户时区发送邮件。示例："America/New_York"。
filterstring否将邮件发送给符合特定筛选条件的用户。
devicesarray否用于发送定向邮件的邮箱地址列表（最多 1000 个）。如果使用此参数，消息将仅发送给这些地址。如果使用 Application Group，则此参数将被忽略。
use_auto_registrationboolean否如果为 true，则自动注册 devices 参数中的邮箱。
usersarray否如果设置，邮件消息将仅发送给指定的 User ID（通过 /registerEmail 调用注册）。数组中不超过 1000 个用户 ID。如果指定了 “devices” 参数，则 “users” 参数将被忽略。
dynamic_content_placeholdersobject否用于动态内容的占位符，以替代设备标签值。
conditionsarray否使用标签的细分条件。示例：[["Country", "EQ", "BR"]]。
fromobject否指定自定义的发件人姓名和邮箱，覆盖应用程序属性中的默认设置。
reply-toobject否指定自定义的回复邮箱，覆盖应用程序属性中的默认设置。
email_typestring否指定邮件类型："marketing" 或 "transactional"。
email_categorystring当 email_type 为 "marketing" 时必需。指定在订阅偏好中心中配置的类别名称之一（例如 Newsletter、Promotional、Product Updates）。
transactionIdstring否唯一的消息标识符，用于在网络问题时防止重复发送。在 Pushwoosh 端存储 5 分钟。
capping_daysinteger否对每个设备应用频率上限的天数（最多 30 天）。注意： 确保已在控制面板中配置全局频率上限。
capping_countinteger否在 capping_days 周期内，可从特定应用发送到特定设备的最大邮件数。如果创建的消息超出了设备的 capping_count 限制，则不会发送到该设备。
capping_excludeboolean否如果设置为 true，此邮件将不计入未来邮件的频率上限。
capping_avoidboolean否如果设置为 true，频率上限将不适用于此特定邮件。
send_rateinteger否限制所有用户每秒可发送的消息数量。有助于在高流量发送期间防止后端过载。
send_rate_avoidboolean否如果设置为 true，则节流限制将不适用于此特定邮件。

请求示例

Anchor link to
{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // 必需。来自 Pushwoosh 控制面板的 API access token
    "application": "APPLICATION_CODE",  // 必需。Pushwoosh application code。
    "notifications": [{
      "send_date": "now",               // 必需。YYYY-MM-DD HH:mm 或 'now'
      "preset": "ERXXX-32XXX",          // 必需。从 Pushwoosh 控制面板的邮件内容编辑器
                                        //           页面 URL 栏中复制邮件预设代码。
      "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" //           默认“发件人姓名”和“发件人邮箱”。
      },
      "reply-to": {                     // 可选。指定一个邮箱地址以替换
        "name": "alias reply to ",      //           应用程序属性中设置的默认“回复至”。
        "email": "reply-to@email.com"
      },
      "email_type": "marketing",        // 可选。"marketing" 或 "transactional"。
      "email_category": "category name",// 当 email_type 为 "marketing" 时必需。类别名称。
      "transactionId": "unique UUID",   // 可选。唯一的消息标识符，用于在网络问题时防止
                                        //           重复发送。在 Pushwoosh 端存储 5 分钟。
      // 频率上限参数。确保已在控制面板中配置全局频率上限。
      "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，节流限制将不适用于
                                        //           此特定邮件。
    }]
  }
}

响应示例

Anchor link to
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

标签条件

Anchor link to

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

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

操作数描述

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

字符串标签

Anchor link to

有效操作符：EQ、IN、NOTEQ、NOTIN
有效操作数：

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

整数标签

Anchor link to

有效操作符：EQ、IN、NOTEQ、NOTIN、BETWEEN、GTE、LTE
有效操作数：

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

日期标签

Anchor link to

有效操作符：EQ、IN、NOTEQ、NOTIN、BETWEEN、GTE、LTE
有效操作数：

  • "YYYY-MM-DD 00:00" (字符串)
  • unix 时间戳 1234567890 (整数)
  • "N days ago" (字符串)，适用于 EQ、BETWEEN、GTE、LTE 操作符

布尔标签

Anchor link to

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

列表标签

Anchor link to

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

registerEmail

Anchor link to

为应用注册邮箱地址。

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

请求头

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

请求体

Anchor link to
名称类型描述
application*stringPushwoosh application code
email*string邮箱地址。
languagestring设备的语言区域设置。必须是符合 ISO-639-1 标准的小写双字母代码。
userIdstring与邮箱地址关联的 User ID。
tz_offsetinteger时区偏移量（秒）。
tagsobject要分配给已注册设备的标签值。
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
示例
{
  "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
    }
  }
}

deleteEmail

Anchor link to

从您的用户群中移除邮箱地址。

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

请求头

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

请求体

Anchor link to
名称类型描述
applicationstringPushwoosh application code
emailstring在 /registerEmail 请求中使用的邮箱地址。
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
示例
{
  "request": {
    "application": "APPLICATION_CODE",  // 必需。Pushwoosh application code
    "email": "email@domain.com"         // 必需。要从应用订阅者中删除的邮箱。
  }
}

setEmailTags

Anchor link to

为邮箱地址设置标签值。

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

请求头

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

请求体

Anchor link to
名称类型描述
applicationstringPushwoosh application code
emailstring邮箱地址。
tagsobject要设置的标签的 JSON 对象，发送 ‘null’ 以移除值。
userIdstring与邮箱地址关联的 User ID。
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}
示例
{
  "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。
  }
}

registerEmailUser

Anchor link to

将外部 User ID 与指定的邮箱地址关联。

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

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

请求头

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

请求体

Anchor link to
名称类型描述
application*stringPushwoosh application code
email*string邮箱地址。
userId*string与邮箱地址关联的 User ID。
tz_offsetinteger时区偏移量（秒）。
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
示例
{
  "request": {
    "application": "APPLICATION_CODE", // 必需。Pushwoosh application code。
    "email": "email@domain.com",       // 必需。用户邮箱地址。
    "userId": "userId",                // 必需。与邮箱地址关联的用户 ID。
    "tz_offset": 3600                  // 可选。时区偏移量（秒）。
  }
}