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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.stats.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username
[
{
"date": "2014-11-27",
"requests": 0,
"delivered": 0,
"bounces": 0,
"repeat_bounces": 0,
"unsubscribes": 0,
"repeat_unsubscribes": 0,
"clicks": 0,
"opens": 0,
"spamreports": 0,
"repeat_spamreports": 0,
"invalid_email": 0,
"blocks": 0,
"unique_clicks": 0,
"unique_opens": 0
}
]
POST
https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username
<stats>
<day>
<date>2014-11-29</date>
<requests>0</requests>
<delivered>0</delivered>
<bounces>0</bounces>
<repeat_bounces>0</repeat_bounces>
<unsubscribes>0</unsubscribes>
<repeat_unsubscribes>0</repeat_unsubscribes>
<clicks>0</clicks>
<opens>0</opens>
<spamreports>0</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 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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.stats.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&aggregate=1
{
"requests": "12342",
"bounces": "12",
"clicks": "10223",
"opens": "9992",
"spamreports": "5"
}
POST
https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&aggregate=1
<stats>
<requests>12342</requests>
<bounces>12</bounces>
<clicks>10223</clicks>
<opens>9992</opens>
<spamreports>5</spamreports>
</stats>
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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.stats.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&list=true
[
{
"category": "categoryA"
},
{
"category": "categoryB"
},
{
"category": "categoryC"
}
]
POST
https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&list=true
<categories>
<category>categoryA</category>
<category>categoryB</category>
<category>categoryC</category>
</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
JSON
XML
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
[
{
"date": "2009-06-20",
"category": "categoryA",
"requests": 12342,
"bounces": 12,
"clicks": 10223,
"opens": 9992,
"spamreports": 5
}
]
POST
https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category=categoryA
<stats>
<day>
<date>2009-06-20</date>
<category>categoryA</category>
<requests>12342</requests>
<bounces>12</bounces>
<clicks>10223</clicks>
<opens>9992</opens>
<spamreports>5</spamreports>
</day>
</stats>
When retrieving statistics for more than one category, use an array category argument.
JSON
XML
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
[
{
"date": "2009-06-20",
"category": "categoryA",
"requests": 12342,
"bounces": 12,
"clicks": 10223,
"opens": 9992,
"spamreports": 5
},
{
"date": "2009-06-21",
"category": "categoryB",
"requests": 32342,
"bounces": 10,
"clicks": 14323,
"opens": 10995,
"spamreports": 7
}
]
POST
https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&category[]=categoryA&category[]=categoryB
<stats>
<day>
<date>2009-06-20</date>
<category>categoryA</category>
<requests>12342</requests>
<bounces>12</bounces>
<clicks>10223</clicks>
<opens>9992</opens>
<spamreports>5</spamreports>
</day>
<day>
<date>2009-06-21</date>
<category>categoryB</category>
<requests>32342</requests>
<bounces>10</bounces>
<clicks>14323</clicks>
<opens>10995</opens>
<spamreports>7</spamreports>
</day>
</stats>
