Statistics

Statistics of delivery data (per day)

Email data counted by day

URL 

https://api.sendcloud.net/apiv2/statday/list

HTTP Request Method 

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
days int * stats in the past [days] days (days=1 means today)
startDate string * start date, formatted with yyyy-MM-dd
endDate string * end date, formatted with yyyy-MM-dd
apiUserList string no obtain stats of specified API_USER; multiple API_USERs are separated by semicolons, for example,apiUserList=a;b;c
labelIdList string no obtain stats of specified label; multiple labels are separated by semicolons, for example,labelIdList=a;b;c
labelNameList string no obtain stats of specified label name; multiple labels are separated by semicolons(the Chinese character is encoded in UTF-8), for example,labelNameList=a;b;c
domainList string no obtain stats in specified domian; multiple domains are separated by semicolons, for example, domainList=a;b;c
aggregate boolean(1, 0) no defaults to 0; if aggregate=1, aggregated data will be returned

Tips:

  1. pecified time span is required when obtaining stats. Note: start_date and end_date, or [days] is required.
  2. Time span cannot be longer than 3 months.
  3. Whenaggregate=1, all data will be aggregated.
  4. When labelIdList and labelNameList are provided at the same time, the labelIdList is preferred for precise query; When only labelNameList is provided, fuzzy query is performed with all labelNames in the list

Request Example:

https://api.sendcloud.net/apiv2/statday/list?apiUser=***&apiKey=***&days=2&domainList=***;***

https://api.sendcloud.net/apiv2/statday/list?apiUser=***&apiKey=***&startDate=2015-02-01&endDate=2015-02-28&apiUserList=***;***

https://api.sendcloud.net/apiv2/statday/list?apiUser=***&apiKey=***&startDate=2015-02-01&endDate=2015-02-28&apiUserList=***;***&aggregate=1

Returned value description

parameter description
sendDate send date
apiUser API_USER
domain domain
labelId label ID
labelName label name
requestNum total requests
deliveredNum deliveries
clickNum clicks
openNum opens
bounceNum soft bounces
spamReportedNum number of spam reporting
unsubscribeNum unsubscribes
uniqueOpensNum unique opens
uniqueClicksNum unique clicks
invalidEmailsNum number of invalid emails
deliveredPercent percentage of deliveries
clickPercent percentage of clicks
openPercent percentage of opens
bouncePercent percentage of bounces
spamReportedPercent percentage of spam reporting
unsubscribePercent percentage of unsubscribes
uniqueOpensPercent percentage of unique opens
uniqueClicksPercent percentage of unique clicks
invalidEmailsPercent percentage of invalid emails

Returned value example:

{
    "statusCode":200,
    "info": {
       "dataList": [
         {
            "sendDate": "2015-03-12",
            "apiUser": "...",
            "domain": "ifaxin.com",
            "labelId": 0,
            "labelName": null,
            "requestNum": 20,
            "deliveredNum": 0,
            "clickNum": 0,
            "openNum": 0,
            "bounceNum": 0,
            "spamReportedNum": 0,
            "unsubscribeNum": 0,
            "uniqueOpensNum": 0,
            "uniqueClicksNum": 0,
            "invalidEmailsNum": 20,
            "deliveredPercent": 0,
            "clickPercent": 0,
            "openPercent": 0,
            "bouncePercent": 0,
            "spamReportedPercent": 0,
            "unsubscribePercent": 0,
            "uniqueOpensPercent": 0,
            "uniqueClicksPercent": 0,
            "invalidEmailsPercent": 100
          },
          {
            "sendDate": "2015-03-12",
            "apiUser": "...",
            "domain": "qq.com",
            "labelId": 0,
            "labelName": null,
            "requestNum": 27,
            "deliveredNum": 27,
            "clickNum": 0,
            "openNum": 0,
            "bounceNum": 0,
            "spamReportedNum": 0,
            "unsubscribeNum": 0,
            "uniqueOpensNum": 0,
            "uniqueClicksNum": 0,
            "invalidEmailsNum": 0,
            "deliveredPercent": 100,
            "clickPercent": 0,
            "openPercent": 0,
            "bouncePercent": 0,
            "spamReportedPercent": 0,
            "unsubscribePercent": 0,
            "uniqueOpensPercent": 0,
            "uniqueClicksPercent": 0,
            "invalidEmailsPercent": 0
          }
      ]
    },
    "message": "请求成功",
    "result": true
}

# 聚合数据, aggregate = 1
{
    "statusCode":200,
    "info": {
      "dataList": {
        "requestNum": "48",
        "deliveredNum": "28",
        "clickNum": "0",
        "openNum": "0",
        "bounceNum": "0",
        "spamReportedNum": "0",
        "unsubscribeNum": "0",
        "uniqueOpenNum": "0",
        "uniqueClickNum": "0",
        "invalidEmailNum": "20",
        "deliveredPercent": 58.33,
        "clickPercent": 0,
        "openPercent": 0,
        "bouncePercent": 0,
        "spamReportedPercent": 0,
        "unsubscribePercent": 0,
        "uniqueOpensPercent": 0,
        "uniqueClicksPercent": 0,
        "invalidEmailsPercent": 41.66
      },
    "message": "请求成功",
    "result": true
}

Statistics of delivery data (per hour)

Email data counted by hour

URL 

https://api.sendcloud.net/apiv2/stathour/list

HTTP Request Method 

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
days int * stats in the past [days] days (days=1 means today)
startDate string * start date, formatted with yyyy-MM-dd
endDate string * end date, formatted with yyyy-MM-dd
apiUserList string no obtain stats of specified API_KEY; multiple API_KEYs are separated by semicolons, for example,apiUserList=a;b;c
labelIdList string no obtain stats in specified label; multiple labels are separated by semicolons, for example,labelIdList=a;b;c
labelNameList string no obtain stats of specified label name; multiple labels are separated by semicolons(the Chinese character is encoded in UTF-8), for example,labelNameList=a;b;c

Tips:

  1. Specified time span is required when obtaining stats. Note:start_date and end_date or days is required.
  2. Time span cannot be longer than 3 months.
  3. When labelIdList and labelNameList are provided at the same time, the labelIdList is preferred for precise query; When only labelNameList is provided, fuzzy query is performed with all labelNames in the list

Request Example: 

https://api.sendcloud.net/apiv2/stathour/list?apiUser=***&apiKey=***&days=2

https://api.sendcloud.net/apiv2/stathour/list?apiUser=***&apiKey=***&startDate=2015-02-01&endDate=2015-02-28&apiUserList=***;***

Returned value description

parameter description
sendDate send date
apiUser API_USER
labelId label ID
labelName label name
sendHour an hour, within [0 – 23]
domain Receiving domain
requestNum total requests
deliveredNum deliveries
clickNum clicks
openNum opens
bounceNum soft bounces
spamReportedNum number of spam reporting
unsubscribeNum unsubscribes
uniqueOpensNum unique opens
uniqueClicksNum unique clicks
invalidEmailsNum number of invalid emails
deliveredPercent percentage of deliveries
clickPercent percentage of clicks
openPercent percentage of opens
bouncePercent percentage of bounces
spamReportedPercent percentage of spam reporting
unsubscribePercent percentage of unsubscribes
uniqueOpensPercent percentage of unique opens
uniqueClicksPercent percentage of unique clicks
invalidEmailsPercent percentage of invalid emails

Returned value example:

# sendHour 没有返回的时间点, 表示那个小时没有数据
{


    "statusCode":200,
    "info":{
      "dataList": [
           {
            "sendDate": "2015-03-12",
            "apiUser": "...",
            "labelId": 0,
            "labelName": "",
            "sendHour": 10, # 10点请求的邮件数据,
            "domain": '163.com',
            "requestNum": 8,
            "deliveredNum": 3,
            "clickNum": 0,
            "openNum": 0,
            "bounceNum": 0,
            "spamReportedNum": 0,
            "unsubscribeNum": 0,
            "uniqueOpensNum": 0,
            "uniqueClicksNum": 0,
            "invalidEmailsNum": 5,
            "deliveredPercent": 75,
            "clickPercent": 0,
            "openPercent": 0,
            "bouncePercent": 0,
            "spamReportedPercent": 0,
            "unsubscribePercent": 0,
            "uniqueOpensPercent": 0,
            "uniqueClickspercent": 0,
            "invalidEmailsPercent": 62.5
           }
       ],
    "message": "请求成功",
    "result": true
}

Statistics of invalid emails

Query classified stats of invalid emails

URL 

https://api.sendcloud.net/apiv2/invalidstat/list

HTTP Request Method 

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
days int * stats in the past [days] days (days=1 means today)
startDate string * start date, formatted with yyyy-MM-dd
endDate string * end date, formatted with yyyy-MM-dd
apiUserList string no obtain stats of specified API_USER, mutiple API_USERs are separated by semicolons, for example, apiUserList=a;b;c
labelIdList string no obtain stats of specified label; multiple labels are separated by semicolons, for example, labelIdList=a;b;c
labelNameList string no obtain stats of specified label name; multiple labels are separated by semicolons(the Chinese character is encoded in UTF-8), for example,labelNameList=a;b;c
domainList string no obtain stats in specified domian; multiple domains are separated by semicolons, for example, domainList=a;b;c
aggregate int(1, 0) no defaults to 0; if aggregate=1, aggregated data will be returned

Tips:

  1. Specified time span is required when obtaining stats. Note: startDate and endDate or days is required.
  2. Whenaggregate=1,all data will be aggregated.
  3. When labelIdList and labelNameList are provided at the same time, the labelIdList is preferred for precise query; When only labelNameList is provided, fuzzy query is performed with all labelNames in the list

Request Example: 

https://api.sendcloud.net/apiv2/invalidstat/list?apiUser=***&apiKey=***&startDate=2015-03-12&endDate=2015-03-12

Returned value description

parameter description
sendDate send date, formatted with yyyy-MM-dd
apiUser API_USER
labelId label ID
labelName label name
domain domain
sendcloudBlacklist count of emails in SendCloud blacklist
ubsubscribe count of emails in unsubscribe list
espUnvaliable unavailable esp severs
recipientAddressError invalid recipient addresses
ipOrDomainRejected rejected IPs or domains
recipientNotFound nonexistent recipients
spamEmails count of spam emails
senderOrRecipientRejected rejected senders or recipients
others others

Example of Returned value: 

{
  "statusCode":200,
  "info":{
    "dataList":[
       {
        "sendDate":"2016-02-01",
        "apiUser":"postmaster@delong.sendcloud.org",
        "labelId":5285,
        "labelName":"中文测试1", 
        "domain":"gmail.com",
        "sendcloudBlacklist":1,
        "ubsubscribe":0,
        "espUnvaliable":0,
        "recipientAddressError":0,
        "recipientNotFound":0,
        "spamEmail":0,
        "senderOrRecipientRejected":0,
        "others":0
       }
   ]
  },
  "message": "请求成功",
  "result": true
}