View and Edit

Statistics

Subuser Statistics

Retrieve Subuser Statistics

Retrieve daily statistics for a subuser.

The days argument and the start_date/end_date arguments are exclusive from each other.

URI Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to retrieve statistics from
days No Unsigned Integer Number of days in the past to include statistics (includes today)
start_date No Date must be in YYY-mm-dd format and be before the end_date parameter Beginning of date range
end_date No Date must be in YYY-mm-dd format and be after the start_date parameter End of date range
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.stats.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

[
  {
    "date": "2014-11-27",
    "requests": 0,
    "delivered": 0,
    "bounces": 0,
    "repeat_bounces": 0,
    "unsubscribes": 0,
    "repeat_unsubscribes": 0,
    "clicks": 0,
    "opens": 0,
    "spamreports": 0,
    "repeat_spamreports": 0,
    "invalid_email": 0,
    "blocks": 0,
    "unique_clicks": 0,
    "unique_opens": 0
  }
]

Call

POST https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<stats>
  <day>
    <date>2014-11-29</date>
    <requests>0</requests>
    <delivered>0</delivered>
    <bounces>0</bounces>
    <repeat_bounces>0</repeat_bounces>
    <unsubscribes>0</unsubscribes>
    <repeat_unsubscribes>0</repeat_unsubscribes>
    <clicks>0</clicks>
    <opens>0</opens>
    <spamreports>0</spamreports>
    <repeat_spamreports>0</repeat_spamreports>
    <invalid_email>0</invalid_email>
    <blocks>0</blocks>
    <unique_clicks>0</unique_clicks>
    <unique_opens>0</unique_opens>
  </day>
</stats>

Retrieve Aggregate Statistics

Retrieve lifetime total statistics for a subuser.

URI Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to retrieve statistics from
aggregate Yes Must be set to 1 argument to provide total statistics instead of daily
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.stats.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&aggregate=1

Response

1
2
3
4
5
6
7

{
  "requests": "12342",
  "bounces": "12",
  "clicks": "10223",
  "opens": "9992",
  "spamreports": "5"
}

Call

POST https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&aggregate=1

Response

1
2
3
4
5
6
7

<stats>
   <requests>12342</requests>
   <bounces>12</bounces>
   <clicks>10223</clicks>
   <opens>9992</opens>
   <spamreports>5</spamreports>
</stats>

Category List

Retrieve a list of all the categories used by a subuser.

URI Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to pull categories from
list Yes The value must be set to true Task to retrieve list of categories
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.stats.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&list=true

Response

1
2
3
4
5
6
7
8
9
10
11

[
  {
    "category": "categoryA"
  },
  {
    "category": "categoryB"
  },
  {
    "category": "categoryC"
  }
]

Call

POST https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&list=true

Response

1
2
3
4
5

<categories>
   <category>categoryA</category>
   <category>categoryB</category>
   <category>categoryC</category>
</categories>

Category Statistics

Retrieve statistics broken down by category. If the category does not exist, it will return an empty result set.

The days argument and the start_date/end_date arguments are exclusive from each other.

URI Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to retrieve statistics from
category Yes Existing category on the account Category to retrieve statistics from
days No Unsigned Integer Number of days in the past to include statistics (includes today)
start_date No Date must be in YYY-mm-dd format and be before the end_date parameter Beginning of date range
end_date No Date must be in YYY-mm-dd format and be after the start_date parameter End of date range
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.stats.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category=categoryA

Response

1
2
3
4
5
6
7
8
9
10
11

[
  {
    "date": "2009-06-20",
    "category": "categoryA",
    "requests": 12342,
    "bounces": 12,
    "clicks": 10223,
    "opens": 9992,
    "spamreports": 5
  }
]

Call

POST https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category=categoryA

Response

1
2
3
4
5
6
7
8
9
10
11

<stats>
  <day>
    <date>2009-06-20</date>
    <category>categoryA</category>
    <requests>12342</requests>
    <bounces>12</bounces>
    <clicks>10223</clicks>
    <opens>9992</opens>
    <spamreports>5</spamreports>
  </day>
</stats>

Multiple Category Statistics

When retrieving statistics for more than one category, use an array category argument.

Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.stats.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category[]=categoryA&category[]=categoryB

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

[
  {
    "date": "2009-06-20",
    "category": "categoryA",
    "requests": 12342,
    "bounces": 12,
    "clicks": 10223,
    "opens": 9992,
    "spamreports": 5
  },
  {
    "date": "2009-06-21",
    "category": "categoryB",
    "requests": 32342,
    "bounces": 10,
    "clicks": 14323,
    "opens": 10995,
    "spamreports": 7
  }
]

Call

POST https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category[]=categoryA&category[]=categoryB

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<stats>
  <day>
    <date>2009-06-20</date>
    <category>categoryA</category>
    <requests>12342</requests>
    <bounces>12</bounces>
    <clicks>10223</clicks>
    <opens>9992</opens>
    <spamreports>5</spamreports>
  </day>
  <day>
      <date>2009-06-21</date>
      <category>categoryB</category>
      <requests>32342</requests>
      <bounces>10</bounces>
      <clicks>14323</clicks>
      <opens>10995</opens>
      <spamreports>7</spamreports>
  </day>
</stats>