We store 7 days of email activity in our database and the default is 500 items returned per request via these API endpoints.

Advanced Stats provide a more in-depth view of your statistics and the actions of the recipients segmented by geography, browser type, and more. You can read more about them in the Statistics section of our User Guide.

GET

Gets email statistics by country and state/province.

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
country No US|CA See statistics for a given country. Only supported for US and CA.

Request

1
GET https://api.sendgrid.com/v3/geo/stats?start_date=2015-01-01&end_date=2015-01-02 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
HTTP/1.1 200
[
  {
    "date": "2014-10-01",
    "stats": [
      {
        "metrics": {
          "clicks": 0,
          "opens": 1,
          "unique_clicks": 0,
          "unique_opens": 1
        },
        "name": "US",
        "type": "country"
      }
    ]
  },
  {
    "date": "2014-10-02",
    "stats": [
      {
        "metrics": {
          "clicks": 0,
          "opens": 0,
          "unique_clicks": 0,
          "unique_opens": 0
        },
        "name": "US",
        "type": "country"
      }
    ]
  }
]

GET

Gets email statistics by device type.

Available device types:

Device Description
Desktop Email software on desktop computer I.E. Outlook, Sparrow, or Apple Mail.
Webmail A web-based email client I.E. Yahoo, Google, AOL, or Outlook.com.
Phone A smart phone; iPhone, Android, Blackberry, etc.
Tablet A tablet computer: iPad, android based tablet, etc.
Other An unrecognized Device.
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

Request

1
GET https://api.sendgrid.com/v3/devices/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week 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
HTTP/1.1 200
[
  {
    "date": "2014-10-01",
    "stats": [
      {
        "metrics": {
          "opens": 1,
          "unique_opens": 1
        },
        "name": "Webmail",
        "type": "device"
      }
    ]
  },
  {
    "date": "2014-10-02",
    "stats": [
      {
        "metrics": {
          "opens": 0,
          "unique_opens": 0
        },
        "name": "Webmail",
        "type": "device"
      }
    ]
  }
]

GET

Gets email statistics by client type.

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

Request

1
GET https://api.sendgrid.com/v3/clients/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week 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
HTTP/1.1 200
[
  {
    "date": "2014-10-01",
    "stats": [
      {
        "metrics": {
          "opens": 1,
          "unique_opens": 1
        },
        "name": "Gmail",
        "type": "client"
      }
    ]
  },
  {
    "date": "2014-10-02",
    "stats": [
      {
        "metrics": {
          "opens": 0,
          "unique_opens": 0
        },
        "name": "Gmail",
        "type": "client"
      }
    ]
  }
]

GET

Gets email statistics for a single client type.

URI Parameter Required Requirements Description
client_type Yes phone|tablet|webmail|desktop Specifies the type of client to retrieve stats for.
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

Request

1
GET https://api.sendgrid.com/v3/clients/:client_type/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week 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
HTTP/1.1 200
[
  {
    "date": "2014-10-01",
    "stats": [
      {
        "metrics": {
          "opens": 1,
          "unique_opens": 1
        },
        "name": "Gmail",
        "type": "client"
      }
    ]
  },
  {
    "date": "2014-10-02",
    "stats": [
      {
        "metrics": {
          "opens": 0,
          "unique_opens": 0
        },
        "name": "Gmail",
        "type": "client"
      }
    ]
  }
]

GET

Gets email statistics by mailbox provider.

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
mailbox_providers No Array of strings The mailbox providers to get statistics for, up to 10

Request

1
GET https://api.sendgrid.com/v3/mailbox_providers/stats?start_date=2015-01-01&end_date=2015-01-02 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
HTTP/1.1 200
[
  {
    "date": "2014-10-01",
    "stats": [
      {
        "metrics": {
          "blocks": 1,
          "bounces": 0,
          "clicks": 0,
          "deferred": 1,
          "delivered": 1,
          "drops": 0,
          "opens": 1,
          "spam_reports": 0,
          "unique_clicks": 0,
          "unique_opens": 1
        },
        "name": "Gmail",
        "type": "esp"
      }
    ]
  },
  {
    "date": "2014-10-02",
    "stats": [
      {
        "metrics": {
          "blocks": 0,
          "bounces": 0,
          "clicks": 0,
          "deferred": 0,
          "delivered": 0,
          "drops": 0,
          "opens": 0,
          "spam_reports": 0,
          "unique_clicks": 0,
          "unique_opens": 0
        },
        "name": "Gmail",
        "type": "esp"
      }
    ]
  }
]

GET

Gets email statistics by browser. You can add multiple browsers to the URL, by using the browsers parameter multiple times.

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
browsers No Array of strings The browsers to get statistics for, up to 10

Request

1
GET https://api.sendgrid.com/v3/browsers/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week 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
HTTP/1.1 200
[
  {
    "date": "2014-10-01",
    "stats": [
      {
        "metrics": {
          "clicks": 0,
          "unique_clicks": 0
        },
        "name": "Chrome",
        "type": "browser"
      },
      {
        "metrics": {
          "clicks": 1,
          "unique_clicks": 1
        },
        "name": "Firefox",
        "type": "browser"
      }
    ]
  },
  {
    "date": "2014-10-02",
    "stats": [
      {
        "metrics": {
          "clicks": 0,
          "unique_clicks": 0
        },
        "name": "Chrome",
        "type": "browser"
      },
      {
        "metrics": {
          "clicks": 1,
          "unique_clicks": 1
        },
        "name": "Firefox",
        "type": "browser"
      }
    ]
  }
]