Customer Statistics
Retrieve Customer Statistics
Note that you can use either the days parameter or the start_date and end_date parameter.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| user | Yes | Customer must be registered under your account | The customer we are retrieving statistics from |
| 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 |
| method | Yes | Must be set to stats |
Allows you to access stats functionality |
To retrieve statistics for the Marketing Emails application, you can use Category Statistics with category=Newsletter parameter.
These are Reseller only APIs. For more information, see Reseller Overview.
Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.json |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com |
Response
[
{
"date": "2009-06-20",
"requests": 12342,
"delivered": 0,
"bounces": 12,
"repeat_bounces": 0,
"unsubscribes": 0,
"repeat_unsubscribes": 0,
"clicks": 10223,
"opens": 9992,
"spamreports": 5,
"repeat_spamreports": 0,
"invalid_email": 0,
"blocks": 0,
"unique_clicks": 0,
"unique_opens": 0
},
{
"date": "2009-06-21",
"requests": 32342,
"delivered": 0,
"bounces": 10,
"repeat_bounces": 0,
"unsubscribes": 0,
"repeat_unsubscribes": 0,
"clicks": 14323,
"opens": 10995,
"spamreports": 7,
"repeat_spamreports": 0,
"invalid_email": 0,
"blocks": 0,
"unique_clicks": 0,
"unique_opens": 0
},
{
"date": "2009-06-22",
"requests": 52342,
"delivered": 0,
"bounces": 11,
"repeat_bounces": 0,
"unsubscribes": 0,
"repeat_unsubscribes": 0,
"clicks": 19223,
"opens": 12992,
"spamreports": 2,
"repeat_spamreports": 0,
"invalid_email": 0,
"blocks": 0,
"unique_clicks": 0,
"unique_opens": 0
}
]Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.xml |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com |
Response
<stats>
<day>
<date>2009-06-20</date>
<requests>12342</requests>
<delivered>9</delivered>
<bounces>12</bounces>
<repeat_bounces>0</repeat_bounces>
<unsubscribes>0</unsubscribes>
<repeat_unsubscribes>0</repeat_unsubscribes>
<clicks>10223</clicks>
<opens>9992</opens>
<spamreports>5</spamreports>
<repeat_spamreports>0</repeat_spamreports>
<invalid_email>0</invalid_email>
<blocks>0</blocks>
<unique_clicks>0</unique_clicks>
<unique_opens>0</unique_opens>
</day>
<day>
<date>2009-06-21</date>
<requests>32342</requests>
<delivered>9</delivered>
<bounces>10</bounces>
<repeat_bounces>0</repeat_bounces>
<unsubscribes>0</unsubscribes>
<repeat_unsubscribes>0</repeat_unsubscribes>
<clicks>14323</clicks>
<opens>10995</opens>
<spamreports>7</spamreports>
<repeat_spamreports>0</repeat_spamreports>
<invalid_email>0</invalid_email>
<blocks>0</blocks>
<unique_clicks>0</unique_clicks>
<unique_opens>0</unique_opens>
</day>
<day>
<date>2009-06-22</date>
<requests>52342</requests>
<delivered>9</delivered>
<bounces>11</bounces>
<repeat_bounces>0</repeat_bounces>
<unsubscribes>0</unsubscribes>
<repeat_unsubscribes>0</repeat_unsubscribes>
<clicks>19223</clicks>
<opens>12992</opens>
<spamreports>2</spamreports>
<repeat_spamreports>0</repeat_spamreports>
<invalid_email>0</invalid_email>
<blocks>0</blocks>
<unique_clicks>0</unique_clicks>
<unique_opens>0</unique_opens>
</day>
</stats>Retrieve Aggregates
Retrieve all-time totals for your customer
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| user | Yes | Customer must be registered under your account | The customer we are retrieving statistics from |
| aggregate | Yes | Must be set to 1 | This is used to let us know that you are interested in all-time totals |
| method | Yes | Must be set to stats |
Allows you to access stats functionality |
Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.json |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com&aggregate=1 |
Response
{
"requests": 12342,
"delivered": 10,
"bounces": 12,
"repeat_bounces": 0,
"unsubscribes": 0,
"repeat_unsubscribes": 0,
"clicks": 10223,
"opens": 9992,
"spamreports": 5,
"repeat_spamreports": 0,
"invalid_email": 1,
"blocks": 0,
"unique_clicks": 0,
"unique_opens": 0
}Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.xml |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com&aggregate=1 |
Response
<stats>
<requests>12342</requests>
<delivered>10</delivered>
<bounces>12</bounces>
<repeat_bounces>0</repeat_bounces>
<unsubscribes>0</unsubscribes>
<repeat_unsubscribes>0</repeat_unsubscribes>
<clicks>10223</clicks>
<opens>9992</opens>
<spamreports>5</spamreports>
<repeat_spamreports>0</repeat_spamreports>
<invalid_email>0</invalid_email>
<blocks>0</blocks>
<unique_clicks>0</unique_clicks>
<unique_opens>0</unique_opens>
</stats>Category List
Retrieve a list of all the categories used in your customer's account.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| list | Yes | The value must be set to true |
This will allow you to retrieve a list of all categories used in your customer's account. |
| user | Yes | Customer must be registered under your account | The customer we are retrieving category statistics from |
| method | Yes | Must be set to stats |
Allows you to access stats functionality |
Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.json |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com&list=true |
Response
[
{
"category": "categoryA"
},
{
"category": "categoryB"
},
{
"category": "categoryC"
}
]Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.xml |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com&list=true |
Response
<categories>
<category>categoryA</category>
<category>categoryB</category>
<category>categoryC</category>
</categories>Category Statistics
Category statistics are available for the previous thirteen months only.
Retrieve statistics broken down by category. If the category does not exist, there will be an empty result set.
Note that you can use either the days parameter or the start_date and end_date parameter.
| URI Parameter | Required | Requirements | Description |
|---|---|---|---|
| category | Yes | Must be an existing category that has statistics. You can pass in an array of categories | The category you will specify to retrieve detailed stats |
| user | Yes | Customer must be registered under you | The customer we are retrieving statistics from |
| 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 |
| method | Yes | Must be set to stats |
Allows you to access stats functionality |
Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.json |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com&start_date=2009-06-20&end_date=2009-06-22&category=category |
Response
[
{
"category": "CategoryA",
"delivered": 1,
"unsubscribes": 0,
"invalid_email": 0,
"bounces": 0,
"repeat_unsubscribes": 0,
"unique_clicks": 0,
"blocked": 0,
"spam_drop": 0,
"repeat_bounces": 0,
"repeat_spamreports": 0,
"date": "2014-09-09",
"requests": 1,
"spamreports": 0,
"clicks": 0,
"opens": 0,
"unique_opens": 0
},
{
"category": "CategoryB",
"delivered": 1,
"unsubscribes": 0,
"invalid_email": 0,
"bounces": 0,
"repeat_unsubscribes": 0,
"unique_clicks": 0,
"blocked": 0,
"spam_drop": 0,
"repeat_bounces": 0,
"repeat_spamreports": 0,
"date": "2014-09-08",
"requests": 1,
"spamreports": 0,
"clicks": 0,
"opens": 0,
"unique_opens": 0
}
]Call
| POST | https://api.sendgrid.com/apiv2/reseller.manage.xml |
| POST Data | api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=stats&user=eexampexample@example.com&start_date=2009-06-20&end_date=2009-06-22&category=category |
Response
<stats>
<day>
<category>CategoryA</category>
<delivered>1</delivered>
<unsubscribes>0</unsubscribes>
<invalid_email>0</invalid_email>
<bounces>0</bounces>
<repeat_unsubscribes>0</repeat_unsubscribes>
<unique_clicks>0</unique_clicks>
<blocked>0</blocked>
<spam_drop>0</spam_drop>
<repeat_bounces>0</repeat_bounces>
<repeat_spamreports>0</repeat_spamreports>
<date>2014-09-09</date>
<requests>1</requests>
<spamreports>0</spamreports>
<clicks>0</clicks>
<opens>0</opens>
<unique_opens>0</unique_opens>
</day>
<day>
<category>CategoryB</category>
<delivered>1</delivered>
<unsubscribes>0</unsubscribes>
<invalid_email>0</invalid_email>
<bounces>0</bounces>
<repeat_unsubscribes>0</repeat_unsubscribes>
<unique_clicks>0</unique_clicks>
<blocked>0</blocked>
<spam_drop>0</spam_drop>
<repeat_bounces>0</repeat_bounces>
<repeat_spamreports>0</repeat_spamreports>
<date>2014-09-08</date>
<requests>1</requests>
<spamreports>0</spamreports>
<clicks>0</clicks>
<opens>0</opens>
<unique_opens>0</unique_opens>
</day>
</stats>Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
