openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Bounces 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: Bounces
  description: 'Twilio SendGrid Suppressions API: Bounces operations'
paths:
  /v3/suppression/bounces:
    get:
      operationId: ListSuppressionBounces
      summary: Retrieve all bounces
      tags:
      - Bounces
      description: '**This endpoint allows you to retrieve a paginated list of all your bounces.**


        You can use the `limit` query parameter to set the page size. If your list contains more items than the page size permits, you can make multiple requests. Use the `offset` query parameter to control the position in the list from which to start retrieving additional items.'
      parameters:
      - name: start_time
        in: query
        description: Refers start of the time range in unix timestamp when a bounce was created (inclusive).
        schema:
          type: integer
      - name: end_time
        in: query
        description: Refers end of the time range in unix timestamp when a bounce was created (inclusive).
        schema:
          type: integer
      - $ref: '#/components/parameters/PaginationCommonLimit'
      - $ref: '#/components/parameters/PaginationCommonOffset'
      - name: Accept
        in: header
        required: true
        schema:
          type: string
          default: application/json
      - $ref: '#/components/parameters/EmailPartialMatch'
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BounceResponse'
              examples:
                response:
                  value:
                  - created: 1250337600
                    email: example@example.com
                    reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at  https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp '
                    status: 5.1.1
                  - created: 1250337600
                    email: example@example.com
                    reason: '550 5.1.1 <testemail2@testing.com>: Recipient address rejected: User unknown in virtual alias table '
                    status: 5.1.1
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: DeleteSuppressionBounces
      summary: Delete bounces
      tags:
      - Bounces
      description: "**This endpoint allows you to delete all emails on your bounces list.**\n\nThere are two options for deleting bounced emails: \n\n1. You can delete all bounced emails by setting `delete_all` to `true` in the request body. \n2. You can delete a selection of bounced emails by specifying the email addresses in the `emails` array of the request body. \n\n**WARNING:** You can not have both `emails` and `delete_all` set."
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                delete_all:
                  type: boolean
                  description: This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter.
                emails:
                  type: array
                  description: Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.
                  items:
                    type: string
              example:
                delete_all: false
      responses:
        '204':
          description: ''
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/suppression/bounces/{email}:
    get:
      operationId: GetSuppressionBounces
      summary: Retrieve a Bounce
      tags:
      - Bounces
      description: '**This endpoint allows you to retrieve a specific bounce by email address.**'
      parameters:
      - name: email
        in: path
        description: The email address of the specific bounce you would like to retrieve
        required: true
        schema:
          type: string
          format: email
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BounceResponse'
              examples:
                response:
                  value:
                  - created: 1443651125
                    email: bounce1@test.com
                    reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at  https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp '
                    status: 5.1.1
    delete:
      operationId: DeleteSuppressionBounce
      summary: Delete a bounce
      tags:
      - Bounces
      description: '**This endpoint allows you to remove an email address from your bounce list.**'
      parameters:
      - name: email
        in: path
        description: The email address you would like to remove from the bounce list.
        required: true
        schema:
          type: string
          format: email
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/suppression/bounces/classifications:
    get:
      operationId: ListSuppressionBouncesClassifications
      summary: Retrieve bounce classification totals
      tags:
      - Bounces
      description: This endpoint will return the total number of bounces by classification in descending order for each day. You can retrieve the bounce classification totals in CSV format by specifying `"text/csv"` in the Accept header.
      parameters:
      - name: Accept
        in: header
        description: Specifies the content type to be returned by this endpoint. You can choose to receive CSV-formatted data by passing "text/csv" in the header.
        required: true
        schema:
          default: application/json
          type: string
          $ref: '#/components/schemas/Accept'
      - name: start_date
        in: query
        description: The start of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).
        schema:
          type: string
      - name: end_date
        in: query
        description: The end of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).
        schema:
          type: string
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        stats:
                          type: array
                          items:
                            type: object
                            properties:
                              classification:
                                type: string
                                $ref: '#/components/schemas/Classification'
                              count:
                                type: integer
              examples:
                response:
                  value:
                    result:
                    - date: '2022-01-01'
                      stats:
                      - classification: Unclassified
                        count: 35
                      - classification: Invalid Address
                        count: 14
                    - date: '2022-01-02'
                      stats:
                      - classification: Unclassified
                        count: 23
                      - classification: Content
                        count: 4
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/suppression/bounces/classifications/{classification}:
    get:
      operationId: GetSuppressionBouncesClassifications
      summary: Retrieve bounce classification over time by domain stats
      tags:
      - Bounces
      description: This endpoint will return the number of bounces for the classification specified in descending order for each day. You can retrieve the bounce classification totals in CSV format by specifying `"text/csv"` in the Accept header.
      parameters:
      - name: Accept
        in: header
        description: Specifies the content type to be returned by this endpoint. You can choose to receive CSV-formatted data by passing "text/csv" in the header.
        required: true
        schema:
          type: string
          default: application/json
          $ref: '#/components/schemas/Accept1'
      - name: classification
        in: path
        description: 'The classification you want to filter by. Possible values are: `Content`, `Frequency or Volume Too High`, `Invalid Address`, `Mailbox Unavailable`, `Reputation`, `Technical Failure`, `Unclassified`.'
        schema:
          type: string
          $ref: '#/components/schemas/Classification1'
        required: true
      - name: start_date
        in: query
        description: The start of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).
        schema:
          type: string
      - name: end_date
        in: query
        description: The end of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).
        schema:
          type: string
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        stats:
                          type: array
                          items:
                            type: object
                            properties:
                              domain:
                                type: string
                              count:
                                type: integer
              examples:
                response:
                  value:
                    result:
                    - date: '2022-01-01'
                      stats:
                      - domain: example.com
                        count: 35
                      - domain: one.example.com
                        count: 14
                    - date: '2022-01-02'
                      stats:
                      - domain: example.com
                        count: 23
                      - domain: one.example.com
                        count: 4
components:
  schemas:
    Classification:
      type: string
      enum:
      - Content
      - Frequency or Volume Too High
      - Invalid Address
      - Mailbox Unavailable
      - Reputation
      - Technical Failure
      - Unclassified
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: An error message.
              field:
                description: When applicable, this property value will be the field that generated the error.
                nullable: true
                type: string
              help:
                type: object
                description: When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error.
        id:
          type: string
          description: When applicable, this property value will be an error ID.
      example:
        errors:
        - field: field_name
          message: error message
    Classification1:
      type: string
      enum:
      - Content
      - Frequency or Volume Too High
      - Invalid Address
      - Mailbox Unavailable
      - Reputation
      - Technical Failure
      - Unclassified
    Accept1:
      type: string
      enum:
      - application/json
      - text/csv
    BounceResponse:
      title: Bounce Response
      type: object
      properties:
        created:
          type: number
          description: The unix timestamp for when the bounce record was created at SendGrid.
        email:
          type: string
          format: email
          description: The email address that was added to the bounce list.
        reason:
          type: string
          description: The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description.
        status:
          type: string
          description: Enhanced SMTP bounce response
      example:
        created: 1250337600
        email: example@example.com
        reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at  https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp '
        status: 5.1.1
    Accept:
      type: string
      enum:
      - application/json
      - text/csv
  parameters:
    PaginationCommonLimit:
      name: limit
      in: query
      required: false
      description: '`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is 500 items per page.'
      schema:
        type: integer
        minimum: 1
        maximum: 500
    PaginationCommonOffset:
      name: offset
      in: query
      required: false
      description: The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.
      schema:
        type: integer
        minimum: 0
        default: 0
    OnBehalfOf:
      name: on-behalf-of
      in: header
      description: 'The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent''s Subusers or customer accounts. You will use the parent account''s API key when using this header. When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account''s ID (e.g., `on-behalf-of: account-id <account-id>`). When making a call on behalf of a Subuser, the property value should be the Subuser''s username (e.g., `on-behalf-of: <subuser-username>`). It is important to use the Base URL that corresponds to the region of the account or Subuser you specify in the `on-behalf-of` header. See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.'
      required: false
      schema:
        type: string
    EmailPartialMatch:
      name: email
      in: query
      description: Specifies which records to return based on the records' associated email addresses. For example, `sales` returns records with email addresses that start with 'sales', such as `salesdepartment@example.com` or `sales@example.com`.  You can also use `%25` as a wildcard. For example, `%25market` returns records containing email addresses with the string 'market' anywhere in the email address, and `%25market%25tree` returns records containing email addresses with the string 'market' followed by the string 'tree'. Any reserved characters should be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding#Reserved_characters), e.g., the `@` symbol should be encoded as `%40`.
      required: false
      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