We will deprecate this version on February 10, 2025. To access all the latest features and upcoming developments, please see our v3 API. For assistance with transitioning, refer to our migration guide.
Subuser Statistics
Retrieve daily statistics for a subuser.
The days argument and the start_date/end_date arguments are exclusive from each other.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| user | Yes | Subuser must be under your account | Subuser to retrieve statistics from |
| days | No | Unsigned Integer | Number of days in the past to include statistics (includes today) |
| start_date | No | Date must be in YYY-mm-dd format and be before the end_date parameter | Beginning of date range |
| end_date | No | Date must be in YYY-mm-dd format and be after the start_date parameter | End of date range |
POST | https://api.sendgrid.com/apiv2/customer.stats.json |
|---|---|
POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username |
1[2{3"date": "2014-11-27",4"requests": 0,5"delivered": 0,6"bounces": 0,7"repeat_bounces": 0,8"unsubscribes": 0,9"repeat_unsubscribes": 0,10"clicks": 0,11"opens": 0,12"spamreports": 0,13"repeat_spamreports": 0,14"invalid_email": 0,15"blocks": 0,16"unique_clicks": 0,17"unique_opens": 018}19]
Retrieve lifetime total statistics for a subuser.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| user | Yes | Subuser must be under your account | Subuser to retrieve statistics from |
| aggregate | Yes | Must be set to 1 | argument to provide total statistics instead of daily |
Category statistics are available for the previous thirteen months only.
Retrieve a list of all the categories used by a subuser.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| user | Yes | Subuser must be under your account | Subuser to pull categories from |
| list | Yes | The value must be set to true | Task to retrieve list of categories |
Retrieve statistics broken down by category. If the category does not exist, it will return an empty result set.
The days argument and the start_date/end_date arguments are exclusive from each other.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| user | Yes | Subuser must be under your account | Subuser to retrieve statistics from |
| category | Yes | Existing category on the account | Category to retrieve statistics from |
| days | No | Unsigned Integer | Number of days in the past to include statistics (includes today) |
| start_date | No | Date must be in YYY-mm-dd format and be before the end_date parameter | Beginning of date range |
| end_date | No | Date must be in YYY-mm-dd format and be after the start_date parameter | End of date range |
POST | https://api.sendgrid.com/apiv2/customer.stats.json |
|---|---|
POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category=categoryA |
1[2{3"date": "2009-06-20",4"category": "categoryA",5"requests": 12342,6"bounces": 12,7"clicks": 10223,8"opens": 9992,9"spamreports": 510}11]
When retrieving statistics for more than one category, use an array category argument.
POST | https://api.sendgrid.com/apiv2/customer.stats.json |
|---|---|
POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category[]=categoryA&category[]=categoryB |
1[2{3"date": "2009-06-20",4"category": "categoryA",5"requests": 12342,6"bounces": 12,7"clicks": 10223,8"opens": 9992,9"spamreports": 510},11{12"date": "2009-06-21",13"category": "categoryB",14"requests": 32342,15"bounces": 10,16"clicks": 14323,17"opens": 10995,18"spamreports": 719}20]