Retrieve Statistics

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
category No Must be an existing category, or an array of existing categories. The category for which to retrieve detailed stats

Call

POST https://api.sendgrid.com/api/stats.get.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&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
38
[
   {
      "date": "2014-02-26",
      "delivered": 314,
      "unsubscribes": 1,
      "invalid_email": 5,
      "bounces": 9,
      "repeat_unsubscribes": 2,
      "unique_clicks": 65,
      "blocked": 3,
      "spam_drop": 5,
      "repeat_bounces": 8,
      "repeat_spamreports": 9,
      "requests": 350,
      "spamreports": 1,
      "clicks": 78,
      "opens": 80,
      "unique_opens": 70
   },
   {
      "date": "2014-02-27",
      "delivered": 271,
      "unsubscribes": 8,
      "invalid_email": 2,
      "bounces": 8,
      "repeat_unsubscribes": 1,
      "unique_clicks": 82,
      "blocked": 8,
      "spam_drop": 4,
      "repeat_bounces": 5,
      "repeat_spamreports": 9,
      "requests": 308,
      "spamreports": 0,
      "clicks": 103,
      "opens": 90,
      "unique_opens": 83
   }
]

Call

POST https://api.sendgrid.com/api/stats.get.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&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
38
39
40
<?xml version="1.0" encoding="ISO-8859-1"?>

<stats>
  <day>
      <date>2014-02-26</date>
      <delivered>314</delivered>
      <unsubscribes>1</unsubscribes>
      <invalid_email>5</invalid_email>
      <bounces>9</bounces>
      <repeat_unsubscribes>2</repeat_unsubscribes>
      <unique_clicks>65</unique_clicks>
      <blocked>3</blocked>
      <spam_drop>5</spam_drop>
      <repeat_bounces>8</repeat_bounces>
      <repeat_spamreports>9</repeat_spamreports>
      <requests>350</requests>
      <spamreports>1</spamreports>
      <clicks>78</clicks>
      <opens>80</opens>
      <unique_opens>70</unique_opens>
   </day>
   <day>
      <date>2014-02-27</date>
      <delivered>271</delivered>
      <unsubscribes>8</unsubscribes>
      <invalid_email>2</invalid_email>
      <bounces>8</bounces>
      <repeat_unsubscribes>1</repeat_unsubscribes>
      <unique_clicks>82</unique_clicks>
      <blocked>8</blocked>
      <spam_drop>4</spam_drop>
      <repeat_bounces>5</repeat_bounces>
      <repeat_spamreports>9</repeat_spamreports>
      <requests>308</requests>
      <spamreports>0</spamreports>
      <clicks>103</clicks>
      <opens>90</opens>
      <unique_opens>83</unique_opens>
   </day>
</stats>

Category List

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

Call

POST https://api.sendgrid.com/api/stats.get.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&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/api/stats.get.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&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>