SendGrid Subuser Statistics API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Subuser Statistics API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
    url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
  version: 1.0.0
  x-sendgrid:
    libraryPackage: account_provisioning
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Subuser Statistics
  description: 'Twilio SendGrid Subusers API: Statistics Operations'
paths:
  /v3/subusers/{subuser_name}/stats/monthly:
    parameters:
    - $ref: '#/components/parameters/UserName'
    get:
      operationId: ListSubuserMonthlyStat
      summary: Retrieve the monthly email statistics for a single subuser
      tags:
      - Subuser Statistics
      description: '**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**


        When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:

        `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.'
      parameters:
      - name: date
        in: query
        description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD
        required: true
        schema:
          type: string
      - name: sort_by_metric
        in: query
        description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'''
        required: false
        schema:
          type: string
          default: delivered
      - name: sort_by_direction
        in: query
        description: The direction you want to sort.
        required: false
        schema:
          type: string
          default: desc
          $ref: '#/components/schemas/SortByDirection'
      - name: limit
        in: query
        description: Optional field to limit the number of results returned.
        required: false
        schema:
          type: integer
          default: 5
      - name: offset
        in: query
        description: Optional beginning point in the list to retrieve from.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubuserStats'
              examples:
                response:
                  value:
                    date: '2016-02-01'
                    stats:
                    - first_name: John
                      last_name: Doe
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 5
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 10
                        processed: 10
                        requests: 10
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                      name: user1
                      type: subuser
  /v3/subusers/stats:
    get:
      operationId: ListStat
      summary: Retrieve email statistics for your subusers.
      tags:
      - Subuser Statistics
      description: '**This endpoint allows you to retrieve the email statistics for the given subusers.**


        You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser.'
      parameters:
      - name: limit
        in: query
        description: Limits the number of results returned per page.
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: The point in the list to begin retrieving results from.
        required: false
        schema:
          type: integer
      - name: aggregated_by
        in: query
        description: How to group the statistics. Must be either "day", "week", or "month".
        required: false
        schema:
          type: string
          $ref: '#/components/schemas/AggregatedBy'
      - name: subusers
        in: query
        description: The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers.
        required: true
        schema:
          type: string
      - name: start_date
        in: query
        description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.
        required: true
        schema:
          type: string
      - name: end_date
        in: query
        description: The end date of the statistics to retrieve. Defaults to today.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryStats'
              examples:
                response:
                  value:
                  - date: '2015-10-01'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-02'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-03'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-04'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-05'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-06'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-07'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-08'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-09'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                  - date: '2015-10-10'
                    stats:
                    - type: subuser
                      name: Matt_subuser
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
  /v3/subusers/stats/monthly:
    get:
      operationId: ListMonthlyStat
      summary: Retrieve monthly stats for all subusers
      tags:
      - Subuser Statistics
      description: '**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**


        When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:

        `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.'
      parameters:
      - name: date
        in: query
        description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD
        required: true
        schema:
          type: string
      - name: subuser
        in: query
        description: A substring search of your subusers.
        required: false
        schema:
          type: string
      - name: sort_by_metric
        in: query
        description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'''
        required: false
        schema:
          type: string
          default: delivered
          $ref: '#/components/schemas/SortByMetric'
      - name: sort_by_direction
        in: query
        description: The direction you want to sort.
        required: false
        schema:
          type: string
          default: desc
          $ref: '#/components/schemas/SortByDirection1'
      - name: limit
        in: query
        description: Optional field to limit the number of results returned.
        required: false
        schema:
          type: integer
          default: 5
      - name: offset
        in: query
        description: Optional beginning point in the list to retrieve from.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubuserStats'
              examples:
                response:
                  value:
                    date: '2016-02-01'
                    stats:
                    - first_name: John
                      last_name: Doe
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 1
                        processed: 0
                        requests: 100
                        spam_report_drops: 0
                        spam_reports: 99
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                      name: user1
                      type: subuser
                    - first_name: Jane
                      last_name: Doe
                      metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 5
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 10
                        processed: 10
                        requests: 10
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                      name: user2
                      type: subuser
  /v3/subusers/stats/sums:
    get:
      operationId: ListStatSum
      summary: Retrieve the totals for each email statistic metric for all subusers.
      tags:
      - Subuser Statistics
      description: '**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**'
      parameters:
      - name: sort_by_direction
        in: query
        description: 'The direction you want to sort. '
        required: false
        schema:
          type: string
          default: desc
          $ref: '#/components/schemas/SortByDirection2'
      - name: start_date
        in: query
        description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.
        required: true
        schema:
          type: string
      - name: end_date
        in: query
        description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Limits the number of results returned per page.
        required: false
        schema:
          type: integer
          default: 5
      - name: offset
        in: query
        description: The point in the list to begin retrieving results from.
        required: false
        schema:
          type: integer
          default: 0
      - name: aggregated_by
        in: query
        description: How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: sort_by_metric
        in: query
        description: The metric that you want to sort by.  Must be a single metric.
        required: false
        schema:
          type: string
          default: delivered
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryStats'
              examples:
                response:
                  value:
                    date: '2015-10-11'
                    stats:
                    - metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                      name: cat1
                      type: category
                    - metrics:
                        blocks: 0
                        bounce_drops: 0
                        bounces: 0
                        clicks: 0
                        deferred: 0
                        delivered: 0
                        invalid_emails: 0
                        opens: 0
                        processed: 0
                        requests: 0
                        spam_report_drops: 0
                        spam_reports: 0
                        unique_clicks: 0
                        unique_opens: 0
                        unsubscribe_drops: 0
                        unsubscribes: 0
                      name: cat2
                      type: category
components:
  schemas:
    SortByMetric:
      type: string
      enum:
      - blocks
      - bounces
      - clicks
      - delivered
      - opens
      - requests
      - unique_clicks
      - unique_opens
      - unsubscribes
    SortByDirection2:
      type: string
      enum:
      - desc
      - asc
    SubuserStats:
      title: subuser_stats
      type: object
      properties:
        date:
          type: string
          description: The date the statistics were gathered.
        stats:
          type: array
          description: The list of statistics.
          items:
            type: object
            properties:
              first_name:
                type: string
                description: The first name of the subuser.
              last_name:
                type: string
                description: The last name of the subuser.
              metrics:
                type: object
                properties:
                  blocks:
                    type: integer
                    description: The number of emails that were not allowed to be delivered by ISPs.
                  bounce_drops:
                    type: integer
                    description: The number of emails that were dropped because of a bounce.
                  bounces:
                    type: integer
                    description: The number of emails that bounced instead of being delivered.
                  clicks:
                    type: integer
                    description: The number of links that were clicked in your emails.
                  deferred:
                    type: integer
                    description: The number of emails that temporarily could not be delivered.
                  delivered:
                    type: integer
                    description: The number of emails SendGrid was able to confirm were actually delivered to a recipient.
                  invalid_emails:
                    type: integer
                    description: The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid.
                  opens:
                    type: integer
                    description: The total number of times your emails were opened by recipients.
                  processed:
                    type: integer
                    description: Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed.
                  requests:
                    type: integer
                    description: The number of emails that were requested to be delivered.
                  spam_report_drops:
                    type: integer
                    description: The number of emails that were dropped due to a recipient previously marking your emails as spam.
                  spam_reports:
                    type: integer
                    description: The number of recipients who marked your email as spam.
                  unique_clicks:
                    type: integer
                    description: The number of unique recipients who clicked links in your emails.
                  unique_opens:
                    type: integer
                    description: The number of unique recipients who opened your emails.
                  unsubscribe_drops:
                    type: integer
                    description: The number of emails dropped due to a recipient unsubscribing from your emails.
                  unsubscribes:
                    type: integer
                    description: The number of recipients who unsubscribed from your emails.
              name:
                type: string
                description: The username of the subuser.
              type:
                type: string
                description: The type of account.
      example:
        date: '2016-02-01'
        stats:
        - first_name: John
          last_name: Doe
          metrics:
            blocks: 0
            bounce_drops: 0
            bounces: 0
            clicks: 5
            deferred: 0
            delivered: 0
            invalid_emails: 0
            opens: 10
            processed: 10
            requests: 10
            spam_report_drops: 0
            spam_reports: 0
            unique_clicks: 0
            unique_opens: 0
            unsubscribe_drops: 0
            unsubscribes: 0
          name: user1
          type: subuser
    CategoryStats:
      title: 'Stats: Category Stats'
      type: object
      properties:
        date:
          type: string
          description: The date the statistics were gathered.
        stats:
          type: array
          items:
            type: object
            properties:
              metrics:
                type: object
                properties:
                  blocks:
                    type: integer
                    description: The number of emails that were not allowed to be delivered by ISPs.
                  bounce_drops:
                    type: integer
                    description: The number of emails that were dropped because of a bounce.
                  bounces:
                    type: integer
                    description: The number of emails that bounced instead of being delivered.
                  clicks:
                    type: integer
                    description: The number of links that were clicked.
                  deferred:
                    type: integer
                    description: The number of emails that temporarily could not be delivered.
                  delivered:
                    type: integer
                    description: The number of emails SendGrid was able to confirm were actually delivered to a recipient.
                  invalid_emails:
                    type: integer
                    description: The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid.
                  opens:
                    type: integer
                    description: The total number of times your emails were opened by recipients.
                  processed:
                    type: integer
                    description: Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed.
                  requests:
                    type: integer
                    description: The number of emails that were requested to be delivered.
                  spam_report_drops:
                    type: integer
                    description: The number of emails that were dropped due to a recipient previously marking your emails as spam.
                  spam_reports:
                    type: integer
                    description: The number of recipients who marked your email as spam.
                  unique_clicks:
                    type: integer
                    description: The number of unique recipients who clicked links in your emails.
                  unique_opens:
                    type: integer
                    description: The number of unique recipients who opened your emails.
                  unsubscribe_drops:
                    type: integer
                    description: The number of emails dropped due to a recipient unsubscribing from your emails.
                  unsubscribes:
                    type: integer
                    description: The number of recipients who unsubscribed from your emails.
                required:
                - blocks
                - bounce_drops
                - bounces
                - clicks
                - deferred
                - delivered
                - invalid_emails
                - opens
                - processed
                - requests
                - spam_report_drops
                - spam_reports
                - unique_clicks
                - unique_opens
                - unsubscribe_drops
                - unsubscribes
              name:
                type: string
                description: The name of the category.
              type:
                type: string
                description: How you are segmenting your statistics.
            required:
            - type
      required:
      - date
      example:
        date: '2015-01-01'
        stats:
        - metrics:
            blocks: 0
            bounce_drops: 0
            bounces: 0
            clicks: 0
            deferred: 0
            delivered: 0
            invalid_emails: 0
            opens: 0
            processed: 0
            requests: 0
            spam_report_drops: 0
            spam_reports: 0
            unique_clicks: 0
            unique_opens: 0
            unsubscribe_drops: 0
            unsubscribes: 0
          name: cat1
          type: category
        - metrics:
            blocks: 0
            bounce_drops: 0
            bounces: 0
            clicks: 0
            deferred: 0
            delivered: 0
            invalid_emails: 0
            opens: 0
            processed: 0
            requests: 0
            spam_report_drops: 0
            spam_reports: 0
            unique_clicks: 0
            unique_opens: 0
            unsubscribe_drops: 0
            unsubscribes: 0
          name: cat2
          type: category
    AggregatedBy:
      type: string
      enum:
      - day
      - week
      - month
    SortByDirection1:
      type: string
      enum:
      - desc
      - asc
    SortByDirection:
      type: string
      enum:
      - desc
      - asc
  parameters:
    UserName:
      name: subuser_name
      in: path
      required: true
      description: The username of the Subuser.
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid