Statistics

Retrieve Statistics

Info You can specify either the days parameter or the start_date and end_date parameters. If provided with no parameters, the current day’s statistics are returned.

Parameters

Parameter Required Requirements Description
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
aggregate No 0 or 1 This is used to indicate you are interested in all-time totals

Call

1

https://sendgrid.com/api/stats.get.json?api_user=youremail@domain.com&api_key=secureSecret&days=2

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
29
30
31
32
33
34
35

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

Call

1

https://sendgrid.com/api/stats.get.xml?api_user=youremail@domain.com&api_key=secureSecret&days=2

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
29
30
31
32
33
34
35
36
37

<?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>
      <unique_clicks>3</unique_clicks>
      <unique_opens>6</unique_opens>
      <blocked>7</blocked>
   </day>
   <day>
      <date>2009-06-21</date>
      <requests>32342</requests>
      <bounces>10</bounces>
      <clicks>14323</clicks>
      <opens>10995</opens>
      <spamreports>7</spamreports>
      <unique_clicks>3</unique_clicks>
      <unique_opens>9</unique_opens>
      <blocked>4</blocked>
   </day>
   <day>
      <date>2009-06-22</date>
      <requests>52342</requests>
      <bounces>11</bounces>
      <clicks>19223</clicks>
      <opens>12992</opens>
      <spamreports>2</spamreports>
      <unique_clicks>5</unique_clicks>
      <unique_opens>2</unique_opens>
      <blocked>8</blocked>
   </day>
</stats>

Category List

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

Call

1

https://sendgrid.com/api/stats.get.json?api_user=youremail@domain.com&api_key=secureSecret&list=true

Response

1
2
3
4
5
6
7
8
9
10
11

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

Call

1

https://sendgrid.com/api/stats.get.xml?api_user=youremail@domain.com&api_key=secureSecret&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>

Category Statistics

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

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

Parameters

Parameter Required Requirements Description
category Yes Must be an existing category that has statistics. The category you will specify to retrieve detailed stats
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
aggregate No 0 or 1 This is used to indicate you are interested in all-time totals

Call

1

https://sendgrid.com/api/stats.get.json?api_user=youremail@domain.com&api_key=secureSecret&start_date=2009-06-20&end_date=2009-06-22&category=categoryA

Call - Using an array of categories

1

https://sendgrid.com/api/stats.get.json?api_user=youremail@domain.com&api_key=secureSecret&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
23
24
25
26

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

Call

1

https://sendgrid.com/api/stats.get.xml?api_user=youremail@domain.com&api_key=secureSecret&start_date=2009-06-20&end_date=2009-06-22&category=categoryA

Call - Using an array of categories

1

https://sendgrid.com/api/stats.get.xml?api_user=youremail@domain.com&api_key=secureSecret&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>