Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

Rate this page:

Statistics

Subuser Statistics

Retrieve 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

Call

POST https://api.sendgrid.com/apiv2/customer.stats.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

[
  {
    "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
  }
]

Call

POST https://api.sendgrid.com/apiv2/customer.stats.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

<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 Aggregate Statistics

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

Call

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

Response

{
  "requests": "12342",
  "bounces": "12",
  "clicks": "10223",
  "opens": "9992",
  "spamreports": "5"
}

Call

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

Response

<stats>
   <requests>12342</requests>
   <bounces>12</bounces>
   <clicks>10223</clicks>
   <opens>9992</opens>
   <spamreports>5</spamreports>
</stats>

Category List

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

Call

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

Response

[
  {
    "category": "categoryA"
  },
  {
    "category": "categoryB"
  },
  {
    "category": "categoryC"
  }
]

Call

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

Response

<categories>
   <category>categoryA</category>
   <category>categoryB</category>
   <category>categoryC</category>
</categories>

Category Statistics

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

Call

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

Response

[
  {
    "date": "2009-06-20",
    "category": "categoryA",
    "requests": 12342,
    "bounces": 12,
    "clicks": 10223,
    "opens": 9992,
    "spamreports": 5
  }
]

Call

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

Response

<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>

Multiple Category Statistics

When retrieving statistics for more than one category, use an array category argument.

Call

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

Response

[
  {
    "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
  }
]

Call

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

Response

<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>
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more