投递回应

查询

用户发送的邮件状态列表

你可以对此列表进行查询操作

URL

https://api.sendcloud.net/apiv2/data/emailStatus

HTTP请求方式

post    get

参数说明

参数 类型 必须 说明
apiUser string API_USER
apiKey string API_KEY
email 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

注意:

  1. 获取投递数据时, 必须指定时间区间. 即 startDate 与 endDate 的组合 或者 days 参数 需二者取一.
  2. 查询的天数不超过三天.
  3. 每次查询默认只查询100条记录,如果用户查询满足条件的记录数超过100时候,需要人为指定start和limit参数.
  4. 每次查询得到的对应的记录会根据用户所传参数缓存10分钟.
  5. 此接口限制每个用户账户,每分钟调用接口3000次,超过此频率接口返回 {"result":false,"statusCode":50000,"message":"接口频率受限","info":{}}
  6. status传参取值:1、4、5、18(分别对应送达、无效邮件、软退信、请求中状态)
  7. 同时提供了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 发送日志

说明:

  1. 无效邮件对应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"
            }
        ]
    }
}