SendGrid Invalid Emails API

openapi: 3.2.0
info:
  title: Twilio SendGrid Suppressions Invalid Emails 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.
  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
security:
- BearerAuth: []
tags:
- name: Invalid Emails
  description: 'Twilio SendGrid Suppressions API: Invalid Emails operations'
paths:
  /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.**


        There are two options for deleting invalid email addresses:


        1) You can delete all invalid email addresses by setting `delete_all` to true in the request body.

        2) 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: ''
components:
  parameters:
    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
    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
  schemas:
    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
  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