Category Stats provide all of your user’s email statistics for your categories. Category Stats (and all stats) are only available for the last 3 years.

GET statistics

Gets email statistics for the given categories. If you don’t pass any parameters, the endpoint will return a sum for each category 10 at a time.

URI Parameter Required Requirements Description
start_date Yes Date formatted as YYYY-MM-DD The starting date of the statistics to retrieve
end_date No Date formatted as YYYY-MM-DD The end date of the statistics to retrieve. Defaults to today.
aggregated_by No Must be day|week|month How to group the statistics
categories Yes String The categories to get statistics for, up to 10

Request

1
GET https://api.sendgrid.com/v3/categories/stats?start_date=2015-01-01&end_date=2015-01-02&categories=cat1&categories=cat2 HTTP/1.1

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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
HTTP/1.1 200
[
  {
    "date": "2015-01-01",
    "stats": [
      {
        "metrics": {
          "blocks": 0,
          "bounce_drops": 0,
          "bounces": 0,
          "clicks": 0,
          "deferred": 0,
          "delivered": 0,
          "invalid_emails": 0,
          "opens": 0,
          "processed": 0,
          "requests": 0,
          "spam_report_drops": 0,
          "spam_reports": 0,
          "unique_clicks": 0,
          "unique_opens": 0,
          "unsubscribe_drops": 0,
          "unsubscribes": 0
        },
        "name": "cat1",
        "type": "category"
      },
      {
        "metrics": {
          "blocks": 0,
          "bounce_drops": 0,
          "bounces": 0,
          "clicks": 0,
          "deferred": 0,
          "delivered": 0,
          "invalid_emails": 0,
          "opens": 0,
          "processed": 0,
          "requests": 0,
          "spam_report_drops": 0,
          "spam_reports": 0,
          "unique_clicks": 0,
          "unique_opens": 0,
          "unsubscribe_drops": 0,
          "unsubscribes": 0
        },
        "name": "cat2",
        "type": "category"
      }
    ]
  },
  {
    "date": "2015-01-02",
    "stats": [
      {
        "metrics": {
          "blocks": 10,
          "bounce_drops": 0,
          "bounces": 0,
          "clicks": 0,
          "deferred": 0,
          "delivered": 0,
          "invalid_emails": 0,
          "opens": 0,
          "processed": 0,
          "requests": 10,
          "spam_report_drops": 0,
          "spam_reports": 0,
          "unique_clicks": 0,
          "unique_opens": 0,
          "unsubscribe_drops": 0,
          "unsubscribes": 0
        },
        "name": "cat1",
        "type": "category"
      },
      {
        "metrics": {
          "blocks": 0,
          "bounce_drops": 0,
          "bounces": 0,
          "clicks": 6,
          "deferred": 0,
          "delivered": 5,
          "invalid_emails": 0,
          "opens": 6,
          "processed": 0,
          "requests": 5,
          "spam_report_drops": 0,
          "spam_reports": 0,
          "unique_clicks": 5,
          "unique_opens": 5,
          "unsubscribe_drops": 0,
          "unsubscribes": 6
        },
        "name": "cat2",
        "type": "category"
      }
    ]
  }
]

GET Sums

Gets the total sums of each email statistic metric for all categories over the given date range.

URI Parameter Required Requirements Description
start_date Yes Date formatted as YYYY-MM-DD The starting date of the statistics to retrieve
end_date No Date formatted as YYYY-MM-DD The end date of the statistics to retrieve. Defaults to today.
aggregate_by No Must be day|week|month How to group the statistics
sort_by_metric No A single metric The metric that you want to sort by. Defaults to delivered.
sort_by_direction No [desc|asc] The direction you want to sort. Defaults to desc.
limit No Some integer. Optional field to limit the number of results returned. Defaults to 5.
offset No Some integer. Optional beginning point in the list to retrieve from. Defaults to 0.

Request

1
GET /v3/categories/stats/sums?start_date={start_date}&end_date={end_date}&aggregated_by={aggregated_by}&sort_by_metric={sort_by_metric}&sort_by_direction={sort_by_direction}&limit={limit}&offset={offset} HTTP/1.1

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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
HTTP/1.1 200
{
  "date": "2015-01-01",
  "stats": [
    {
      "metrics": {
        "blocks": 0,
        "bounce_drops": 0,
        "bounces": 0,
        "clicks": 20,
        "deferred": 0,
        "delivered": 20,
        "invalid_emails": 0,
        "opens": 20,
        "processed": 0,
        "requests": 20,
        "spam_report_drops": 0,
        "spam_reports": 0,
        "unique_clicks": 20,
        "unique_opens": 20,
        "unsubscribe_drops": 0,
        "unsubscribes": 20
      },
      "name": "cat1",
      "type": "category"
    },
    {
      "metrics": {
        "blocks": 1,
        "bounce_drops": 0,
        "bounces": 0,
        "clicks": 19,
        "deferred": 0,
        "delivered": 19,
        "invalid_emails": 0,
        "opens": 19,
        "processed": 0,
        "requests": 20,
        "spam_report_drops": 0,
        "spam_reports": 0,
        "unique_clicks": 19,
        "unique_opens": 19,
        "unsubscribe_drops": 0,
        "unsubscribes": 19
      },
      "name": "cat2",
      "type": "category"
    },
    {
      "metrics": {
        "blocks": 0,
        "bounce_drops": 0,
        "bounces": 0,
        "clicks": 5,
        "deferred": 0,
        "delivered": 5,
        "invalid_emails": 0,
        "opens": 5,
        "processed": 0,
        "requests": 5,
        "spam_report_drops": 0,
        "spam_reports": 0,
        "unique_clicks": 5,
        "unique_opens": 5,
        "unsubscribe_drops": 0,
        "unsubscribes": 5
      },
      "name": "cat3",
      "type": "category"
    },
    {
      "metrics": {
        "blocks": 0,
        "bounce_drops": 0,
        "bounces": 0,
        "clicks": 6,
        "deferred": 0,
        "delivered": 5,
        "invalid_emails": 0,
        "opens": 6,
        "processed": 0,
        "requests": 5,
        "spam_report_drops": 0,
        "spam_reports": 0,
        "unique_clicks": 5,
        "unique_opens": 5,
        "unsubscribe_drops": 0,
        "unsubscribes": 6
      },
      "name": "cat4",
      "type": "category"
    },
    {
      "metrics": {
        "blocks": 10,
        "bounce_drops": 0,
        "bounces": 0,
        "clicks": 0,
        "deferred": 0,
        "delivered": 0,
        "invalid_emails": 0,
        "opens": 0,
        "processed": 0,
        "requests": 10,
        "spam_report_drops": 0,
        "spam_reports": 0,
        "unique_clicks": 0,
        "unique_opens": 0,
        "unsubscribe_drops": 0,
        "unsubscribes": 0
      },
      "name": "cat5",
      "type": "category"
    }
  ]
}