投递回应

查询

用户发送的邮件状态列表

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

URL

https://api2.sendcloud.net/api/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	否	用户创建的标签对应的标签名
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

请求参数字典：

subStatus	含义
401	无效邮件-SendCloud黑名单中
402	无效邮件-取消订阅
403	无效邮件-服务器不可达
404	无效邮件-地址格式错误
405	无效邮件-IP、域名被拒
406	无效邮件-地址不存在
407	无效邮件-垃圾邮件
408	无效邮件-发件人/收件人被拒
409	无效邮件-其他
503	软退信-服务不可达
505	软退信-IP、域名被拒
506	软退信-邮箱地址不存在
507	软退信-反垃圾邮件被拒
508	软退信-发件人/收件人被拒
509	软退信-其他

注意:

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进行模糊查询

请求示例:

https://api2.sendcloud.net/api/data/emailStatus?apiUser=***&apiKey=***&days=2&emailIds=***;***

返回参数字典：

status	subStatus	subStatusDesc
delivery	null	null
Invalid Mail-Platform Blacklist	401	SendCloud Blacklist
Invalid Mail - Unsubscribe	402	Unsubscribe
Invalid Mail - Server Unreachable	403	Server Unreachable
Invalid mail - address format error	404	address format error
invalid mail-other	405	IP, domain name rejected
Invalid mail - address does not exist	406	Address does not exist
Invalid Mail - Spam	407	spam
Invalid Mail - Sender / Recipient Rejected	408	Sender/Recipient Rejected
invalid mail-other	409	Other
soft bounce	503	Soft bounce-Server error
soft bounce	505	Soft bounce-IP rejection
soft bounce	506	Soft bounce-Not Exist
soft bounce	507	Soft bounce-Spam rejection
soft bounce	508	Soft bounce-Rejection
soft bounce	509	Soft bounce-Others
Request	null	null

返参说明

1. 无效邮件对应subStatus为4XX，无效子类subStatusDesc分为9个细类；软退信对应subStatus为5xx，软退子类subStatusDesc分为6个细类

返回值示例:

{
    "result":true,
    "statusCode":200,
    "message":"request was successful",
    "info":{
        "total":"2",
        "voListSize":2,
        "voList":[
            {
                "status":"Invalid Mail - Server Unreachable",
                "emailId":"1659283204215_01_31338_6255.sg-10_1_255_122-inbound0$123@test.com",
                "apiUser":"ops",
                "recipients":"123@test.com",
                "requestTime":"2022-08-01 00:00:04",
                "modifiedTime":"2022-08-01 00:02:10",
                "sendLog":"服务器不可达(Cannot establish SMTP connection)",
                "taskName":null,
                "mailingStatus":null,
                "subStatus":403,
                "softStatus":null,
                "timeStr":null,
                "event":null,
                "receiver":"123@test.com",
                "message":null,
                "email":"123@test.com",
                "name":null,
                "phone":null,
                "subStatusDesc":"Server Unreachable"
            },
            {
                "status":"soft bounce",
                "emailId":"1659510170530_01_5967_898.sg-10_1_255_121-inbound0$te@bau.de",
                "apiUser":"ops",
                "recipients":"te@bau.de",
                "requestTime":"2022-08-03 15:02:50",
                "modifiedTime":"2022-08-03 15:11:47",
                "sendLog":"邮箱地址不存在(resolver.adr.recipientnotfound)",
                "taskName":null,
                "mailingStatus":null,
                "subStatus":506,
                "softStatus":null,
                "timeStr":null,
                "event":null,
                "receiver":"te@bau.de",
                "message":null,
                "email":"te@bau.de",
                "name":null,
                "phone":null,
                "subStatusDesc":"Soft bounce-Not Exist"
            }
        ]
    }
}