openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Suppressions 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: Suppressions
  description: Twilio SendGrid Suppressions API
paths:
  /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
components:
  requestBodies:
    PostSuppressions:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuppressionsRequest'
  schemas:
    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
  parameters:
    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
  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