openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Suppressions API
  summary: The Twilio SendGrid Suppressions API allows you to manage your Suppressions
    or Unsubscribes and Suppression or Unsubscribe groups.
  description: 'The Twilio SendGrid Suppressions API allows you to manage your Suppressions
    or Unsubscribes and Suppression or Unsubscribe groups. With SendGrid, an unsubscribe
    is the action an email recipient takes when they opt-out of receiving your messages.
    A suppression is the action you take as a sender to filter or suppress an unsubscribed
    address from your email send. From the perspective of the recipient, your suppression
    is the result of their unsubscribe.


    You can have global suppressions, which represent addresses that have been unsubscribed
    from all of your emails. You can also have suppression groups, also known as ASM
    groups, which represent categories or groups of emails that your recipients can
    unsubscribe from, rather than unsubscribing from all of your messages.


    SendGrid automatically suppresses emails sent to users for a variety of reasons,
    including blocks, bounces, invalid email addresses, spam reports, and unsubscribes.
    SendGrid suppresses these messages to help you maintain the best possible sender
    reputation by attempting to prevent unwanted mail. You may also add addresses
    to your suppressions.


    See [**Suppressions**](https://docs.sendgrid.com/for-developers/sending-email/suppressions)
    for more information.'
  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: suppressions
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
paths:
  /v3/asm/groups:
    post:
      operationId: CreatAsmGroup
      summary: Create a new suppression group
      tags:
      - Unsubscribe Groups
      description: '**This endpoint allows you to create a new suppression group.**


        To add an email address to the suppression group, [create a Suppression](https://docs.sendgrid.com/api-reference/suppressions-suppressions/add-suppressions-to-a-suppression-group).'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuppressionGroupRequestBaseProps'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The ID of the suppression group.
                  name:
                    type: string
                    description: The name of the suppression group.
                  description:
                    type: string
                    description: A brief description of the suppression group.
                  is_default:
                    type: boolean
                    description: Indicates if this is the default suppression group.
                required:
                - id
                - name
                - description
                - is_default
              examples:
                response:
                  value:
                    id: 103
                    name: Product Suggestions
                    description: Suggestions for products our users might like.
                    is_default: false
    get:
      operationId: ListAsmGroup
      summary: Retrieve all suppression groups associated with the user.
      tags:
      - Unsubscribe Groups
      description: '**This endpoint allows you to retrieve a list of all suppression
        groups created by this user.**


        This endpoint can also return information for multiple group IDs that you
        include in your request. To add a group ID to your request, simply append
        `?id=123456&id=123456`, with the appropriate group IDs.'
      parameters:
      - name: id
        in: query
        description: The ID of the suppression group(s) you want to retrieve.
        schema:
          type: integer
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SuppressionGroup'
              examples:
                response:
                  value:
                  - id: 1234
                    name: Unsubscribe Group
                    description: An Unsubscribe Group
                    is_default: true
                    unsubscribes: 1234
                  - id: 1234
                    name: Unsubscribe Group
                    description: An Unsubscribe Group
                    is_default: true
                    unsubscribes: 1234
  /v3/asm/groups/{group_id}:
    parameters:
    - name: group_id
      in: path
      description: The ID of the suppression group you would like to retrieve.
      required: true
      schema:
        type: string
    get:
      operationId: GetAsmGroup
      summary: Get information on a single suppression group.
      tags:
      - Unsubscribe Groups
      description: '**This endpoint allows you to retrieve a single suppression group.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of your suppression group. Required when
                      creating a group.
                    maxLength: 30
                  description:
                    type: string
                    description: A brief description of your suppression group. Required
                      when creating a group.
                    maxLength: 100
                  is_default:
                    type: boolean
                    description: Indicates if you would like this to be your default
                      suppression group.
                  id:
                    type: integer
                    description: The ID of the suppression group.
                  unsubscribes:
                    type: integer
                    description: The number of unsubscribes, or suppressions, in this
                      group.
                required:
                - id
              examples:
                response:
                  value:
                    description: Our monthly newsletter.
                    id: 100
                    is_default: true
                    name: Newsletters
                    unsubscribes: 400
    patch:
      operationId: UpdateAsmGroup
      summary: Update a suppression group.
      tags:
      - Unsubscribe Groups
      description: '**This endpoint allows you to update or change a suppression group.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              example:
                id: 103
                name: Item Suggestions
                description: Suggestions for items our users might like.
              type: object
              properties:
                name:
                  type: string
                  description: The name of your suppression group. Required when creating
                    a group.
                  maxLength: 30
                description:
                  type: string
                  description: A brief description of your suppression group. Required
                    when creating a group.
                  maxLength: 100
                is_default:
                  type: boolean
                  description: Indicates if you would like this to be your default
                    suppression group.
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuppressionGroup'
              examples:
                response:
                  value:
                    id: 103
                    name: Item Suggestions
                    description: Suggestions for items our users might like.
    delete:
      operationId: DeleteAsmGroup
      summary: Delete a Suppression Group
      tags:
      - Unsubscribe Groups
      description: '**This endpoint allows you to delete a suppression group.**


        If a recipient uses the "one-click unsubscribe" option on an email associated
        with a deleted group, that recipient will be added to the global suppression
        list.


        Deleting a suppression group will remove the suppression, meaning email will
        once again be sent to the previously suppressed addresses. This should be
        avoided unless a recipient indicates they wish to receive email from you again.
        You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions)
        to deliver messages to otherwise suppressed addresses when exceptions are
        required.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /v3/asm/groups/{group_id}/suppressions:
    parameters:
    - name: group_id
      in: path
      description: The id of the unsubscribe group that you are adding suppressions
        to.
      required: true
      schema:
        type: string
    post:
      operationId: AddSuppressionToAsmGroup
      summary: Add suppressions to a suppression group
      tags:
      - Suppressions
      description: '**This endpoint allows you to add email addresses to an unsubscribe
        group.**


        If you attempt to add suppressions to a group that has been deleted or does
        not exist, the suppressions will be added to the global suppressions list.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        $ref: '#/components/requestBodies/PostSuppressions'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipient_emails:
                    type: array
                    description: The email addresses you added to the unsubscribe
                      group
                    items:
                      type: string
                      format: email
              examples:
                response:
                  value:
                    recipient_emails:
                    - test1@example.com
                    - test2@example.com
    get:
      operationId: ListSuppressionFromAsmGroup
      summary: Retrieve all suppressions for a suppression group
      tags:
      - Suppressions
      description: '**This endpoint allows you to retrieve all suppressed email addresses
        belonging to the given group.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                description: The list of email addresses belonging to the given suppression
                  group.
                items:
                  type: string
                  format: email
              examples:
                response:
                  value:
                  - example@example.com
                  - example2@example.com
  /v3/asm/groups/{group_id}/suppressions/{email}:
    parameters:
    - name: group_id
      in: path
      description: The id of the suppression group that you are removing an email
        address from.
      required: true
      schema:
        type: string
    - name: email
      in: path
      description: The email address that you want to remove from the suppression
        group.
      required: true
      schema:
        type: string
    delete:
      operationId: DeleteSuppressionFromAsmGroup
      summary: Delete a suppression from a suppression group
      tags:
      - Suppressions
      description: '**This endpoint allows you to remove a suppressed email address
        from the given suppression group.**


        Removing an address will remove the suppression, meaning email will once again
        be sent to the previously suppressed addresses. This should be avoided unless
        a recipient indicates they wish to receive email from you again. You can use
        our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions)
        to deliver messages to otherwise suppressed addresses when exceptions are
        required.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /v3/asm/groups/{group_id}/suppressions/search:
    parameters:
    - name: group_id
      in: path
      description: The ID of the suppression group that you would like to search.
      required: true
      schema:
        type: string
    post:
      operationId: SearchSuppressionFromAsmGroup
      summary: Search for suppressions within a group
      tags:
      - Suppressions
      description: '**This endpoint allows you to search a suppression group for multiple
        suppressions.**


        When given a list of email addresses and a group ID, this endpoint will only
        return the email addresses that have been unsubscribed from the given group.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        $ref: '#/components/requestBodies/PostSuppressions'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                description: The email address from your search that do exist in the
                  suppression group.
                items:
                  type: string
                  format: email
              examples:
                response:
                  value:
                  - exists1@example.com
                  - exists2@example.com
  /v3/asm/suppressions:
    get:
      operationId: ListAsmSuppression
      summary: Retrieve all suppressions
      tags:
      - Suppressions
      description: '**This endpoint allows you to retrieve a list of all suppressions.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    email:
                      type: string
                      description: The email address that was suppressed.
                    group_id:
                      type: integer
                      description: The id of the suppression group that this email
                        address belongs to.
                    group_name:
                      type: string
                      description: The name of the suppression group that this email
                        address belongs to.
                    created_at:
                      type: integer
                      description: A UNIX timestamp indicating when the suppression
                        was created.
                  required:
                  - email
                  - group_id
                  - group_name
                  - created_at
              examples:
                response:
                  value:
                  - email: test1@example.com
                    group_id: 1
                    group_name: Weekly News
                    created_at: 1410986704
                  - email: test1@example.com
                    group_id: 2
                    group_name: Daily News
                    created_at: 1411493671
                  - email: test2@example.com
                    group_id: 2
                    group_name: Daily News
                    created_at: 1411493671
  /v3/asm/suppressions/{email}:
    parameters:
    - name: email
      in: path
      description: The email address that you want to search suppression groups for.
      required: true
      schema:
        type: string
    get:
      operationId: GetAsmSuppression
      summary: Retrieve all suppression groups for an email address
      tags:
      - Suppressions
      description: '**This endpoint returns a list of all groups from which the given
        email address has been unsubscribed.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  suppressions:
                    type: array
                    description: The array of suppression groups.
                    items:
                      type: object
                      properties:
                        description:
                          type: string
                          description: The description of the suppression group.
                        id:
                          type: integer
                          description: The id of the suppression group.
                        is_default:
                          type: boolean
                          description: Indicates if the suppression group  is set
                            as the default.
                        name:
                          type: string
                          description: The name of the suppression group.
                        suppressed:
                          type: boolean
                          description: Indicates if the given email address is suppressed
                            for this group.
                      required:
                      - description
                      - id
                      - is_default
                      - name
                      - suppressed
                required:
                - suppressions
              examples:
                response:
                  value:
                    suppressions:
                    - description: Optional description.
                      id: 1
                      is_default: true
                      name: Weekly News
                      suppressed: true
                    - description: Some daily news.
                      id: 2
                      is_default: true
                      name: Daily News
                      suppressed: true
                    - description: An old group.
                      id: 2
                      is_default: false
                      name: Old News
                      suppressed: false
  /v3/suppression/blocks:
    get:
      operationId: ListSuppressionBlock
      summary: Retrieve all blocks
      tags:
      - Blocks
      description: '**This endpoint allows you to retrieve a paginated list of all
        email addresses that are currently on your blocks list.**


        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: The start of the time range when a blocked email was created
          (inclusive). This is a unix timestamp.
        schema:
          type: integer
      - name: end_time
        in: query
        description: The end of the time range when a blocked email was created (inclusive).
          This is a unix timestamp.
        schema:
          type: integer
      - $ref: '#/components/parameters/PaginationCommonLimit'
      - $ref: '#/components/parameters/PaginationCommonOffset'
      - $ref: '#/components/parameters/EmailPartialMatch'
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocksResponse'
              examples:
                response:
                  value:
                  - created: 1443651154
                    email: example@example.com
                    reason: 'error dialing remote address: dial tcp 10.57.152.165:25:
                      no route to host'
                    status: 4.0.0
                  - created: 1443651155
                    email: example1@example.com
                    reason: 'unable to resolve MX record for example.com: servfail'
                    status: 4.0.0
    delete:
      operationId: DeleteSuppressionBlocks
      summary: Delete blocks
      tags:
      - Blocks
      description: "**This endpoint allows you to delete all email addresses on your\
        \ blocks list.**\n\nThere are two options for deleting blocked emails: \n\n\
        1. You can delete all blocked emails by setting `delete_all` to `true` in\
        \ the request body. \n2. You can delete a selection of blocked emails by specifying\
        \ the email addresses in the `emails` array of the request body."
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                delete_all:
                  type: boolean
                  description: Indicates if you want to delete all blocked email addresses.
                emails:
                  type: array
                  description: The specific blocked email addresses that you want
                    to delete.
                  items:
                    type: string
              example:
                delete_all: false
                emails:
                - example1@example.com
                - example2@example.com
      responses:
        '204':
          description: ''
  /v3/suppression/blocks/{email}:
    parameters:
    - name: email
      in: path
      description: The email address of the specific block.
      required: true
      schema:
        type: string
        format: email
    get:
      operationId: GetSuppressionBlock
      summary: Retrieve a specific block
      tags:
      - Blocks
      description: '**This endpoint allows you to retrieve a specific email address
        from your blocks list.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocksResponse'
              examples:
                response:
                  value:
                  - created: 1443651154
                    email: example@example.com
                    reason: 'error dialing remote address: dial tcp 10.57.152.165:25:
                      no route to host'
                    status: 4.0.0
    delete:
      operationId: DeleteSuppressionBlock
      summary: Delete a specific block
      tags:
      - Blocks
      description: '**This endpoint allows you to delete a specific email address
        from your blocks list.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /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
  /v3/asm/suppressions/global:
    post:
      operationId: CreateGlobalSuppression
      summary: Add recipient addresses to the global suppression group.
      tags:
      - Global Suppressions
      description: '**This endpoint allows you to add one or more email addresses
        to the global suppressions group.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        $ref: '#/components/requestBodies/PostSuppressions'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipient_emails:
                    type: array
                    description: The email addresses that are globally suppressed
                    items:
                      type: string
                      format: email
                required:
                - recipient_emails
              examples:
                response:
                  value:
                    recipient_emails:
                    - test1@example.com
                    - test2@example.com
  /v3/asm/suppressions/global/{email}:
    parameters:
    - name: email
      in: path
      description: The email address of the global suppression you want to retrieve.
        Or, if you want to check if an email address is on the global suppressions
        list, enter that email address here.
      required: true
      schema:
        type: string
    get:
      operationId: GetGlobalSuppression
      summary: Retrieve a Global Suppression
      tags:
      - Global Suppressions
      description: '**This endpoint allows you to retrieve a global suppression. You
        can also use this endpoint to confirm if an email address is already globally
        suppresed.**


        If the email address you include in the URL path parameter `{email}` is already
        globally suppressed, the response will include that email address. If the
        address you enter for `{email}` is not globally suppressed, an empty JSON
        object `{}` will be returned.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Retrieve a Global Suppression response
                type: object
                properties:
                  recipient_email:
                    type: string
                    description: The email address that is globally suppressed. This
                      will be an empty object if the email address you included in
                      your call is not globally suppressed.
                    format: email
                required:
                - recipient_email
              examples:
                response:
                  value:
                    recipient_email: test@example.com
    delete:
      operationId: DeleteGlobalSuppression
      summary: Delete a Global Suppression
      tags:
      - Global Suppressions
      description: '**This endpoint allows you to remove an email address from the
        global suppressions group.**


        Deleting a suppression group will remove the suppression, meaning email will
        once again be sent to the previously suppressed addresses. This should be
        avoided unless a recipient indicates they wish to receive email from you again.
        You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions)
        to deliver messages to otherwise suppressed addresses when exceptions are
        required.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /v3/suppression/invalid_emails:
    get:
      operationId: ListInvalidEmail
      summary: Retrieve all invalid emails
      tags:
      - Invalid Emails
      description: '**This endpoint allows you to retrieve a paginated list of all
        invalid email addresses.**


        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 an invalid
          email was created (inclusive).
        schema:
          type: integer
      - name: end_time
        in: query
        description: Refers end of the time range in unix timestamp when an invalid
          email was created (inclusive).
        schema:
          type: integer
      - $ref: '#/components/parameters/PaginationCommonLimit'
      - $ref: '#/components/parameters/PaginationCommonOffset'
      - name: email
        in: query
        description: This parameter allows you to filter results by email address.
          Only invalid addresses matching an address passed in this parameter will
          be returned.
        schema:
          type: string
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                description: The list of invalid email addresses.
                items:
                  $ref: '#/components/schemas/InvalidEmail'
              examples:
                response:
                  value:
                  - created: 1449953655
                    email: user1@example.com
                    reason: Mail domain mentioned in email address is unknown
                  - created: 1449939373
                    email: user2@example.com
                    reason: Mail domain mentioned in email address is unknown
    delete:
      operationId: DeleteInvalidEmails
      summary: Delete invalid emails
      tags:
      - Invalid Emails
      description: "**This endpoint allows you to remove email addresses from your\
        \ invalid email address list.**\n\nThere are two options for deleting invalid\
        \ email addresses: \n\n1) You can delete all invalid email addresses by setting\
        \ `delete_all` to true in the request body.\n2) You can delete some invalid\
        \ email addresses by specifying certain addresses in an array in the request\
        \ body."
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                delete_all:
                  type: boolean
                  description: Indicates if you want to remove all email address from
                    the invalid emails list.
                emails:
                  type: array
                  description: The list of specific email addresses that you want
                    to remove.
                  items:
                    type: string
                    format: email
              example:
                delete_all: false
                emails:
                - example1@example.com
                - example2@example.com
      responses:
        '204':
          description: ''
  /v3/suppression/invalid_emails/{email}:
    parameters:
    - name: email
      in: path
      description: The specific email address of the invalid email entry that you
        want to retrieve.
      required: true
      schema:
        type: string
    get:
      operationId: GetInvalidEmail
      summary: Retrieve a specific invalid email
      tags:
      - Invalid Emails
      description: '**This endpoint allows you to retrieve a specific invalid email
        addresses.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                description: A specific invalid email.
                minItems: 0
                maxItems: 1
                items:
                  $ref: '#/components/schemas/InvalidEmail'
              examples:
                response:
                  value:
                  - created: 1454433146
                    email: test1@example.com
                    reason: Mail domain mentioned in email address is unknown
    delete:
      operationId: DeleteInvalidEmail
      summary: Delete a specific invalid email
      tags:
      - Invalid Emails
      description: '**This endpoint allows you to remove a specific email address
        from the invalid email address list.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /v3/suppression/spam_reports:
    get:
      operationId: ListSpamReport
      summary: Retrieve all spam reports
      tags:
      - Spam Reports
      description: '**This endpoint allows you to retrieve a paginated list of all
        spam reports.**


        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: The start of the time range when a spam report was created (inclusive).
          This is a unix timestamp.
        schema:
          type: integer
      - name: end_time
        in: query
        description: The end of the time range when a spam report was created (inclusive).
          This is a unix timestamp.
        schema:
          type: integer
      - $ref: '#/components/parameters/PaginationCommonLimit'
      - $ref: '#/components/parameters/PaginationCommonOffset'
      - $ref: '#/components/parameters/EmailPartialMatch'
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpamReportsResponse'
              examples:
                response:
                  value:
                  - created: 1443651141
                    email: user1@example.com
                    ip: 10.63.202.100
                  - created: 1443651154
                    email: user2@example.com
                    ip: 10.63.202.100
    delete:
      operationId: DeleteSpamReports
      summary: Delete spam reports
      tags:
      - Spam Reports
      description: "**This endpoint allows you to delete your spam reports.**\n\n\
        Deleting a spam report will remove the suppression, meaning email will once\
        \ again be sent to the previously suppressed address. This should be avoided\
        \ unless a recipient indicates they wish to receive email from you again.\
        \ You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions)\
        \ to deliver messages to otherwise suppressed addresses when exceptions are\
        \ required.\n\nThere are two options for deleting spam reports: \n\n1. You\
        \ can delete all spam reports by setting the `delete_all` field to `true`\
        \ in the request body.\n2. You can delete a list of select spam reports by\
        \ specifying the email addresses in the `emails` array of the request body."
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                delete_all:
                  type: boolean
                  description: Indicates if you want to delete all email addresses
                    on the spam report list.
                emails:
                  type: array
                  description: A list of specific email addresses that you want to
                    remove from the spam report list.
                  items:
                    type: string
              example:
                delete_all: false
                emails:
                - example1@example.com
                - example2@example.com
      responses:
        '204':
          description: ''
  /v3/suppression/spam_reports/{email}:
    parameters:
    - name: email
      in: path
      description: The email address of a specific spam report that you want to retrieve.
      required: true
      schema:
        type: string
        format: email
    get:
      operationId: GetSpamReport
      summary: Retrieve a specific spam report
      tags:
      - Spam Reports
      description: '**This endpoint allows you to retrieve a specific spam report
        by email address.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpamReportsResponse'
              examples:
                response:
                  value:
                  - created: 1454433146
                    email: test1@example.com
                    ip: 10.89.32.5
    delete:
      operationId: DeleteSpamReport
      summary: Delete a specific spam report
      tags:
      - Spam Reports
      description: '**This endpoint allows you to delete a specific spam report by
        email address.**


        Deleting a spam report will remove the suppression, meaning email will once
        again be sent to the previously suppressed address. This should be avoided
        unless a recipient indicates they wish to receive email from you again. You
        can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions)
        to deliver messages to otherwise suppressed addresses when exceptions are
        required.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /v3/suppression/unsubscribes:
    get:
      operationId: ListGlobalSuppression
      summary: Retrieve all global suppressions
      tags:
      - Global Suppressions
      description: '**This endpoint allows you to retrieve a paginated list of all
        email address that are globally suppressed.**


        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 an unsubscribe
          email was created (inclusive).
        schema:
          type: integer
      - name: end_time
        in: query
        description: Refers end of the time range in unix timestamp when an unsubscribe
          email was created (inclusive).
        schema:
          type: integer
      - $ref: '#/components/parameters/PaginationCommonLimit'
      - $ref: '#/components/parameters/PaginationCommonOffset'
      - $ref: '#/components/parameters/EmailPartialMatch'
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    created:
                      type: integer
                      description: A Unix timestamp indicating when the recipient
                        was added to the global suppression list.
                    email:
                      type: string
                      description: The email address of the recipient who is globally
                        suppressed.
                      format: email
                  required:
                  - created
                  - email
              examples:
                response:
                  value:
                  - created: 1443651141
                    email: user1@example.com
                  - created: 1443651154
                    email: user2@example.com
components:
  schemas:
    SuppressionGroup:
      title: 'Suppressions: Suppression Group'
      type: object
      properties:
        id:
          type: number
          description: The id of the suppression group.
        name:
          type: string
          description: The name of the suppression group. Each group created by a
            user must have a unique name.
          maxLength: 30
        description:
          type: string
          description: A description of the suppression group.
          maxLength: 100
        is_default:
          type: boolean
          default: false
          description: Indicates if this is the default suppression group.
        unsubscribes:
          type: integer
          description: The unsubscribes associated with this group.
      required:
      - id
      - name
      - description
    SuppressionGroupRequestBaseProps:
      title: Suppression Group Request Base
      type: object
      properties:
        name:
          type: string
          description: The name of your suppression group. Required when creating
            a group.
          maxLength: 30
        description:
          type: string
          description: A brief description of your suppression group. Required when
            creating a group.
          maxLength: 100
        is_default:
          type: boolean
          description: Indicates if you would like this to be your default suppression
            group.
    SuppressionsRequest:
      title: Suppressions Request Body
      type: object
      properties:
        recipient_emails:
          type: array
          description: The array of email addresses to add or find.
          items:
            type: string
            format: email
      required:
      - recipient_emails
      example:
        recipient_emails:
        - test1@example.com
        - test2@example.com
    SpamReportsResponse:
      title: Spam Reports Response
      type: array
      items:
        type: object
        properties:
          created:
            type: integer
            description: A Unix timestamp that indicates when the recipient marked
              your message as spam.
          email:
            type: string
            description: The email address of the recipient that marked your message
              as spam.
            format: email
          ip:
            type: string
            description: The IP address that the message was sent from.
        required:
        - created
        - email
        - ip
      example:
      - created: 1443651141
        email: user1@example.com
        ip: 10.63.202.100
      - created: 1443651154
        email: user2@example.com
        ip: 10.63.202.100
    BlocksResponse:
      title: Blocks Response
      type: array
      items:
        type: object
        properties:
          created:
            type: integer
            description: A Unix timestamp indicating when the email address was added
              to the blocks list.
          email:
            type: string
            description: The email address that was added to the block list.
            format: email
          reason:
            type: string
            description: An explanation for the reason of the block.
          status:
            type: string
            description: The status of the block.
        required:
        - created
        - email
        - reason
        - status
      example:
      - created: 1443651154
        email: example@example.com
        reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route
          to host'
        status: 4.0.0
    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
    InvalidEmail:
      title: Invalid Email
      type: object
      properties:
        created:
          type: integer
          description: A Unix timestamp indicating when the email address was added
            to the invalid emails list.
        email:
          type: string
          description: The email address that was marked as invalid.
          format: email
        reason:
          type: string
          description: The reason that the email address was marked as invalid.
      example:
        created: 1620141015
        email: invalid@example.com
        reason: Mail domain mentioned in email address is unknown
    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
    Accept:
      type: string
      enum:
      - application/json
      - text/csv
    Classification:
      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
    Classification1:
      type: string
      enum:
      - Content
      - Frequency or Volume Too High
      - Invalid Address
      - Mailbox Unavailable
      - Reputation
      - Technical Failure
      - Unclassified
  responses: {}
  parameters:
    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
    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
    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
  examples: {}
  requestBodies:
    PostSuppressions:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuppressionsRequest'
  headers: {}
  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.
tags:
- name: Suppressions
  description: Twilio SendGrid Suppressions API
- name: Global Suppressions
  description: 'Twilio SendGrid Suppressions API: Global Suppressions operations'
- name: Unsubscribe Groups
  description: 'Twilio SendGrid Suppressions API: Unsubscribe Group operations'
- name: Blocks
  description: 'Twilio SendGrid Suppressions API: Blocks operations'
- name: Bounces
  description: 'Twilio SendGrid Suppressions API: Bounces operations'
- name: Invalid Emails
  description: 'Twilio SendGrid Suppressions API: Invalid Emails operations'
- name: Spam Reports
  description: 'Twilio SendGrid Suppressions API: Spam Reports operations'
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid