Statistics

Subuser Statistics

Retrieve Subuser Statistics

Note that you can use either the days parameter or the start_date and end_date parameter.

Parameter Required Requirements Description
user Yes Subuser must be registered under your account The subuser we are retrieving statistics from
days No Must be an integer greater than 0 Number of days in the past to include statistics (includes today)
start_date No Date must be in YYYY-mm-dd format and be before the end_date parameter The start date to look up statistics
end_date No Date must be in YYYY-mm-dd format and be after the start_date parameter The end date to look up statistics

Call

1

https://sendgrid.com/apiv2/customer.stats.xml?api_user=username&api_key=secureSecret&user=example@example.com

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<?xml version="1.0" encoding="ISO-8859-1"?>

<stats>
   <day>
      <date>2009-06-20</date>
      <requests>12342</requests>
      <bounces>12</bounces>
      <clicks>10223</clicks>
      <opens>9992</opens>
      <spamreports>5</spamreports>
   </day>
   <day>
      <date>2009-06-21</date>
      <requests>32342</requests>
      <bounces>10</bounces>
      <clicks>14323</clicks>
      <opens>10995</opens>
      <spamreports>7</spamreports>
   </day>
   <day>
      <date>2009-06-22</date>
      <requests>52342</requests>
      <bounces>11</bounces>
      <clicks>19223</clicks>
      <opens>12992</opens>
      <spamreports>2</spamreports>
   </day>
</stats>

Call

1

https://sendgrid.com/apiv2/customer.stats.json?api_user=username&api_key=secureSecret&user=example@example.com

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

[
  {
    "date": "2009-06-20",
    "requests": 12342,
    "bounces": 12,
    "clicks": 10223,
    "opens": 9992,
    "spamreports": 5
  },
  {
    "date": "2009-06-21",
    "requests": 32342,
    "bounces": 10,
    "clicks": 14323,
    "opens": 10995,
    "spamreports": 7
  },
  {
    "date": "2009-06-22",
    "requests": 52342,
    "bounces": 11,
    "clicks": 19223,
    "opens": 12992,
    "spamreports": 2
  }
]

Retrieve Aggregates

Retrieve all-time totals for your subuser

Parameter Required Requirements Description
user Yes Subuser must be registered under your account The subuser we are retrieving statistics from
aggregate Yes Must be set to 1 This is used to let us know that you are interested in all time totals

Call

1

https://sendgrid.com/apiv2/customer.stats.xml?api_user=username&api_key=secureSecret&user=example@example.com&aggregate=1

Response

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Call

Command

1

https://sendgrid.com/apiv2/customer.stats.json?api_user=username&api_key=secureSecret&user=example@example.com&aggregate=1

Response

1
2
3
4
5
6
7

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

Category List

Retrieve a list of all the categories used in your subusers account.

Parameter Required Requirements Description
list Yes The value must be set totrue This will allow you to retrieve a list of all categories used in your subusers account.
user Yes Subuser must be registered under your account The subuser we are retrieving category statistics from

Call

1

https://sendgrid.com/apiv2/customer.stats.xml?api_user=username&api_key=secureSecret&user=example@example.com&list=true

Response

1
2
3
4
5
6
7

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Call

1

https://sendgrid.com/apiv2/customer.stats.json?api_user=username&api_key=secureSecret&user=example@example.com&list=true

Response

1
2
3
4
5

[
  {
    "category": "categoryC"
  }
]

Category Statistics

Retrieve statistics broken down by category. If the category does not exist, there will be an empty result set. Note that you can use  either the days parameter or the start_date and end_date parameter.

Parameter Required Requirements Description
category Yes Must be an existing category that has statistics. You can pass in an array of categories The category you will specify to retrieve detailed stats
user Yes Subuser must be registered under you The subuser we are retrieving statistics from
days No Must be an integer greater than 0 Number of days in the past to include statistics (Includes today)
start_date No Date must be in YYYY-mm-dd format and be before the end_date parameter The start date to look up statistics
end_date No Date must be in YYYY-mm-dd format and be after the start_date parameter The end date to look up statistics

Call

1

https://sendgrid.com/apiv2/customer.stats.xml?api_user=username&api_key=secureSecret&user=example@example.com&start_date=2009-06-20&end_date=2009-06-22&category=categoryA

Call - Using an array of categories

1

https://sendgrid.com/apiv2/customer.stats.xml?api_user=username&api_key=secureSecret&user=example@example.com&start_date=2009-06-20&end_date=2009-06-22&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
21
22

<?xml version="1.0" encoding="ISO-8859-1"?>

<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>

Call

1

https://sendgrid.com/apiv2/customer.stats.json?api_user=username&api_key=secureSecret&user=example@example.com&start_date=2009-06-20&end_date=2009-06-22&category=categoryA

Call - Using an array of categories

1

https://sendgrid.com/apiv2/customer.stats.json?api_user=username&api_key=secureSecret&user=example@example.com&start_date=2009-06-20&end_date=2009-06-22&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
  }
]