投递回应
查询
用户发送的邮件状态列表
你可以对此列表进行查询操作
URL
https://api.sendcloud.net/apiv2/data/emailStatus
HTTP请求方式
post get
参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
apiUser | string | 是 | API_USER |
apiKey | string | 是 | API_KEY |
string | 否 | 收件人地址 | |
emailIds | string | 否 | 调用api发送邮件成功返回的emailId. 多个地址使用';'分隔,如:emailIds=a;b;c |
labelId | string | 否 | 用户创建的标签对应的标签ID |
labelName | string | 否 | 用户创建的标签对应的标签名(中文名称以UTF-8编码) |
days | string | * | 过去 days 天内的投递数据,(days=1表示今天),时间不超过3天 |
startDate | string | * | 开始日期, 格式为yyyy-MM-dd ,和结束时间间隔不超过3天 |
endDate | string | * | 结束日期, 格式为yyyy-MM-dd ,和起始时间间隔不超过3天 |
apiUserList | string | 否 | 用户的多个apiUser. 多个apiUser使用';'分隔,如:apiUserList=a;b;c |
start | string | 否 | 查询起始位置, 取值区间 [0-], 默认为 0 |
limit | int | 否 | 查询个数, 取值区间 [0-100], 默认为 100 |
status | string | 否 | 查询投递回应状态,1 表示送达,4 表示无效邮件,5 表示软退信,18 表示请求中 |
subStatus | string | 否 | 查询无效邮件或软退信子类,多个无效子类使用';'分隔,如:subStatus=a;b;c |
注意:
- 获取投递数据时, 必须指定时间区间. 即 startDate 与 endDate 的组合 或者 days 参数 需二者取一.
- 查询的天数不超过三天.
- 每次查询默认只查询100条记录,如果用户查询满足条件的记录数超过100时候,需要人为指定start和limit参数.
- 每次查询得到的对应的记录会根据用户所传参数缓存10分钟.
- 此接口限制每个用户账户,每分钟调用接口3000次,超过此频率接口返回 {"result":false,"statusCode":50000,"message":"接口频率受限","info":{}}
- status传参取值:1、4、5、18(分别对应送达、无效邮件、软退信、请求中状态)
- 同时提供了labelId和labelName的情况下,优先以labelId为主进行精确查询;仅提供labelName时以labelName进行模糊查询
请求参数字典:
subStatus | 含义 |
---|---|
401 | 无效邮件-SendCloud黑名单中 |
402 | 无效邮件-取消订阅 |
403 | 无效邮件-服务器不可达 |
404 | 无效邮件-地址格式错误 |
405 | 无效邮件-IP、域名被拒 |
406 | 无效邮件-地址不存在 |
407 | 无效邮件-垃圾邮件 |
408 | 无效邮件-发件人/收件人被拒 |
409 | 无效邮件-其他 |
503 | 软退信-服务不可达 |
505 | 软退信-IP、域名被拒 |
506 | 软退信-邮箱地址不存在 |
507 | 软退信-反垃圾邮件被拒 |
508 | 软退信-发件人/收件人被拒 |
509 | 软退信-其他 |
请求示例:
https://api.sendcloud.net/apiv2/data/emailStatus?apiUser=***&apiKey=***&days=2&emailIds=***;***
返回值说明
参数 | 说明 |
---|---|
emailId | 调用api发送邮件成功返回的emailId |
status | 投递状态 |
subStatus | 401-509无效状态码 |
subStatusDesc | 无效或软退信子类描述 |
apiUser | apiUser名称 |
recipients | 收件人地址 |
requestTime | 请求时间 |
modifiedTime | 状态更新时间 |
sendLog | 发送日志 |
说明:
- 无效邮件对应subStatus为4XX,无效子类subStatusDesc分为9个细类;软退信对应subStatus为5xx,软退子类subStatusDesc分为6个细类
返回参数字典:
status | subStatus | subStatusDesc |
---|---|---|
送达 | null | null |
无效邮件-SendCloud黑名单中 | 401 | SendCloud黑名单中 |
无效邮件-取消订阅 | 402 | 取消订阅 |
无效邮件-服务器不可达 | 403 | 服务器不可达 |
无效邮件-地址格式错误 | 404 | 地址格式错误 |
无效邮件-IP、域名被拒 | 405 | IP、域名被拒 |
无效邮件-地址不存在 | 406 | 地址不存在 |
无效邮件-垃圾邮件 | 407 | 垃圾邮件 |
无效邮件-发件人/收件人被拒 | 408 | 发件人/收件人被拒 |
无效邮件-其他 | 409 | 其他 |
软退信 | 503 | 软退信-服务不可达 |
软退信 | 505 | 软退信-IP、域名被拒 |
软退信 | 506 | 软退信-邮箱地址不存在 |
软退信 | 507 | 软退信-反垃圾邮件被拒 |
软退信 | 508 | 软退信-发件人/收件人被拒 |
软退信 | 509 | 软退信-其他 |
请求中 | null | null |
返回值示例:
{
"result" : true,
"statusCode" : 200,
"message" : "请求成功",
"info" : {
"total" : "2",
"voListSize" : 2,
"voList" : [{
"emailId" : "**_**_**_**_**_**_**-**$***@sendcloud.im",
"status" : "送达",
"subStatus" : null,
"subStatusDesc" : null,
"apiUser" : "***",
"recipients" : "###@qq.com",
"requestTime" : "2016-10-18 09:31:59",
"modifiedTime" : "2016-10-18 09:32:08",
"sendLog" : "successfully delivered"
}, {
"emailId" : "**_**_**_**_**_**_**-**$***@sendcloud.im",
"status" : "无效邮件-地址不存在",
"subStatus" : "406",
"subStatDesc" : "地址不存在",
"apiUser" : "***",
"recipients" : "###@qq.com",
"requestTime" : "2016-10-18 09:34:18",
"modifiedTime" : "2016-10-18 09:34:29",
"sendLog" : "unrouteable address"
}
]
}
}