AppPush
WebPush
WhatsApp
Email
SMS
OTP
Marketing Automation
推送计划API
最新更新：2025-04-15
此模块API主要针对的是推送计划ID本身的创建、修改和查询操作。
调用验证
详情参见 REST API 概述的 鉴权方式 说明。
创建与更新推送计划
本接口用于 创建或更新推送计划。通过传入 plan_id 和 plan_description，系统将根据 plan_id 是否存在进行创建或更新操作。
调用地址
POST v4//v4/push_plan
POST v4//v4/push_plan
此代码块在浮窗中显示
请求参数
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| plan_id | string | 是 | 推送计划唯一标识符 |
| plan_description | string | 是 | 推送计划描述信息 |
请求示例
{
"plan_id": "push_20231001_001",
"plan_description": "双十一大促活动推送计划，覆盖全量用户"
}
{
"plan_id": "push_20231001_001",
"plan_description": "双十一大促活动推送计划，覆盖全量用户"
}
此代码块在浮窗中显示
返回参数说明
成功响应
{
"plan_id": "push_20231001_001"
}
{
"plan_id": "push_20231001_001"
}
此代码块在浮窗中显示
失败响应
{
"error": {
"code": 27303,
"message": "Empty plan id"
}
}
{
"error": {
"code": 27303,
"message": "Empty plan id"
}
}
此代码块在浮窗中显示
查询推送计划
本接口用于 分页查询推送计划列表，支持按发送来源过滤和模糊搜索计划描述/计划ID。
调用地址
GET v4/push_plan/list?page_index=x&page_size=xx&send_source=x&search_description=xxx
GET v4/push_plan/list?page_index=x&page_size=xx&send_source=x&search_description=xxx
此代码块在浮窗中显示
请求参数
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| page_index | int | 是 | 分页页码（从 1 开始计数） |
| page_size | int | 是 | 每页数据条数，最大支持 100 条 |
| send_source | int | 否 | 发送来源标识：0-API，1-Web控制台 |
| search_description | string | 否 | 模糊匹配计划描述 或 计划ID（支持中英文、数字、下划线） |
请求示例
GET /v4/push_plan/list?page_index=1&page_size=20&send_source=1&search_description=双十一
GET /v4/push_plan/list?page_index=1&page_size=20&send_source=1&search_description=双十一
此代码块在浮窗中显示
返回参数说明
成功响应
{
"push_plan_info": [
{
"push_id": "push_20231111",
"plan_description": "双十一全站推送计划",
"count": 15,
"create_time": "2023-11-01T10:00:00Z",
"last_used_time": "2023-11-11T20:30:00Z"
}
],
"total": 1
}
{
"push_plan_info": [
{
"push_id": "push_20231111",
"plan_description": "双十一全站推送计划",
"count": 15,
"create_time": "2023-11-01T10:00:00Z",
"last_used_time": "2023-11-11T20:30:00Z"
}
],
"total": 1
}
此代码块在浮窗中显示
失败响应
{
"error": {
"code": 1003,
"message": "Parameter value is invalid"
}
}
{
"error": {
"code": 1003,
"message": "Parameter value is invalid"
}
}
此代码块在浮窗中显示
根据推送计划查询Msgid
本接口用于 获取指定推送计划在最近一个月内的关联消息ID，支持批量查询多个计划的关联消息数据。
调用地址
GET /v4/status/plan/msg/?plan_ids=xxxxxx,xxxxxx&start_date=yyyy-MM-dd&end_date=yyyy-MM-dd
GET /v4/status/plan/msg/?plan_ids=xxxxxx,xxxxxx&start_date=yyyy-MM-dd&end_date=yyyy-MM-dd
此代码块在浮窗中显示
请求参数
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| plan_ids | string | 是 | 推送计划ID列表，多个ID用英文逗号分隔，最多支持100个 |
| start_date | string | 是 | 开始日期（格式：yyyy-MM-dd），必须满足： |
| end_date | string | 是 | 结束日期（格式：yyyy-MM-dd），必须满足： |
请求示例
GET /v4/status/plan/msg/?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-15
GET /v4/status/plan/msg/?plan_ids=push_20231101,push_20231102&start_date=2023-11-01&end_date=2023-11-15
此代码块在浮窗中显示
返回参数说明
成功响应
{
"push_20231101": {
"msg_ids": ["msg_001", "msg_002"]
},
"push_20231102": {
"msg_ids": ["msg_003"]
}
}
{
"push_20231101": {
"msg_ids": ["msg_001", "msg_002"]
},
"push_20231102": {
"msg_ids": ["msg_003"]
}
}
此代码块在浮窗中显示
失败响应
{
"error": {
"code": 21044,
"message": "The time interval exceeds one month."
}
}
{
"error": {
"code": 21044,
"message": "The time interval exceeds one month."
}
}
此代码块在浮窗中显示
错误码说明
| 错误码 | 说明 | 建议处理方式 |
|---|---|---|
| 21015 | 创建推送计划请求参数错误 | 检查 plan_id 或 plan_description 类型是否正确 |
| 27300 | 推送计划标识不合法 | 检查 plan_id 使其符合命名规则 |
| 27301 | 推送计划描述不合法 | 检查 plan_description 使其符合规则 |
| 27303 | 推送计划标识为空 | 创建推送计划时给一个有效的推送计划标识 |
| 27304 | 推送计划标识长度超过限制 | 使推送计划标识长度小于50 |
| 21004 | 创建推送计划权限校验失败 | 确认调用方是否有接口访问权限 |
| 27000 | 服务端内部错误 | 联系技术支持或重试 |
| 1003 | 查询推送计划的参数非法 | 检查 page_index/page_size 是否大于0 |
| 21004 | 查询推送计划权限校验失败 | 确认调用方是否有接口访问权限 |
| 27302 | 超过推送计划使用上限 | 联系技术支持提高上限 |
| 21009 | 系统内部错误,不可重试 | 联系技术支持 |
| 23001 | 根据推送计划查询Msgid权限校验失败 | 确认调用方是否有接口访问权限 |
| 3010 | 查询接口api调用量超出限制 | 联系技术支持 |
| 23002 | 根据推送计划查询Msgid传入有效pl参数错误 | 检查 plan_ids 的有效性 或 日期参数是否传递 |
| 21003 | 传入日期非法 | 检查日期有效性 |
| 21044 | 开始与结束日期间隔超过一个月 | 使开始与结束日期间隔小于一个月 |
