openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Recipients' Data Erasure API
  summary: The Recipients' Data Erasure API allows Twilio SendGrid customers to delete
    their own customers' personal data from the Twilio SendGrid Platform.
  description: The Recipients' Data Erasure API allows Twilio SendGrid customers to
    delete their own customers' personal data from the Twilio SendGrid Platform. The
    use of this API facilitates the self-service removal of email personal data from
    the Twilio SendGrid platform and will enable customers to comply with various
    obligatory data privacy regulations.
  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: recipients_data_erasure
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/recipients/erasejob:
    post:
      operationId: EraseRecipientEmailData
      summary: Erase recipients' email data
      tags:
      - Point Delete System
      description: "**This operation allows you to delete your recipients' personal\
        \ email data**\n\nThe Delete Recipients' Email Data operation accepts a list\
        \ of 5,000 `email_addresses` or a total payload size of 256Kb per request,\
        \ whichever comes first. Upon a successful request with this operation, SendGrid\
        \ will run a search on the email addresses provided against the SendGrid system\
        \ to identify matches. SendGrid will then delete all personal data associated\
        \ with the matched users such as the recipients' names, email addresses, subject\
        \ lines, categories, and IP addresses.\n\nAll email addresses are filtered\
        \ for uniqueness and tested for structural validity\u2014any invalid addresses\
        \ will be returned in an error response.\n\nPlease note that recipient data\
        \ is deleted for the account making the request only\u2014deletions do not\
        \ cascade from a parent account to its Subusers' recipients. To delete a Subuser's\
        \ recipients' data, you can use the `on-behalf-of` header."
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientsDataErasureEraseRecipientsRequest'
            example:
              email_addresses:
              - user1@example.com
              - user2@example.com
      responses:
        '202':
          description: The request was accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientsDataErasureJobId'
        '400':
          $ref: '#/components/responses/RecipientsDataErasure400'
        '401':
          $ref: '#/components/responses/RecipientsDataErasure401'
        '403':
          $ref: '#/components/responses/RecipientsDataErasure403'
        '404':
          $ref: '#/components/responses/RecipientsDataErasure404'
        '429':
          $ref: '#/components/responses/RecipientsDataErasure429'
        '500':
          $ref: '#/components/responses/RecipientsDataErasure500'
components:
  schemas:
    RecipientsDataErasureEraseRecipientsRequest:
      title: EmailAddress
      type: object
      properties:
        email_addresses:
          type: array
          description: List of unique recipient email addresses whose PII will be
            erased. You may include a maximum of 5,000 addresses or a maximum payload
            size of 256Kb, whichever comes first.
          items:
            type: string
          maxItems: 5000
          minItems: 1
      required:
      - email_addresses
      example:
        email_addresses:
        - user1@example.com
        - user2@example.com
    RecipientsDataErasureErrorV1:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: The message representing the error from the API
        field:
          type: string
          description: The field associated with the error
      required:
      - message
      - field
    RecipientsDataErasureJobId:
      title: JobId
      type: object
      properties:
        job_id:
          type: string
          description: The job ID associated with the data erasure request.
      required:
      - job_id
      example:
        job_id: 12a975bd-c742-4713-8f47-cb3ae4e56c74
  responses:
    RecipientsDataErasure400:
      description: The request was formatted incorrectly or missing required parameters.
      content:
        application/json:
          schema:
            title: Bad Request
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/RecipientsDataErasureErrorV1'
            required:
            - errors
          example:
            errors:
            - message: Email_address user1@gml.com is not valid
              field: email_addresses
      headers:
        X-RateLimit-Limit:
          description: The number of requests allowed during the  window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The amount of time (in seconds) until the current window is
            over and the limit is reset
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of request remaining in the 60-second window before
            encountering a 429 error.
          schema:
            type: integer
    RecipientsDataErasure401:
      description: Request lacks valid authentication credentials
      headers:
        X-RateLimit-Limit:
          description: The number of requests allowed during the  window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The amount of time (in seconds) until the current window is
            over and the limit is reset
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of request remaining in the 60-second window before
            encountering a 429 error.
          schema:
            type: integer
      content:
        application/json:
          schema:
            title: Unauthorized
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/RecipientsDataErasureErrorV1'
            required:
            - errors
          example:
            errors:
            - message: Failed to authenticate
              field: ''
    RecipientsDataErasure403:
      description: Not authorized to make the request
      headers:
        X-RateLimit-Limit:
          description: The number of requests allowed during the  window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The amount of time (in seconds) until the current window is
            over and the limit is reset
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of request remaining in the 60-second window before
            encountering a 429 error.
          schema:
            type: integer
      content:
        application/json:
          schema:
            title: Forbidden
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/RecipientsDataErasureErrorV1'
            required:
            - errors
          example:
            errors:
            - message: Not authorized
              field: ''
    RecipientsDataErasure404:
      description: Not Found
      headers:
        X-RateLimit-Limit:
          description: The number of requests allowed during the  window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The amount of time (in seconds) until the current window is
            over and the limit is reset
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of request remaining in the 60-second window before
            encountering a 429 error.
          schema:
            type: integer
      content:
        application/json:
          schema:
            title: Not Found
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/RecipientsDataErasureErrorV1'
            required:
            - errors
          example:
            errors:
            - message: Not Found
              field: ''
    RecipientsDataErasure429:
      description: User has sent too many requests in a given amount of time
      headers:
        X-RateLimit-Limit:
          description: The number of requests allowed during the  window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The amount of time (in seconds) until the current window is
            over and the limit is reset
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of request remaining in the 60-second window before
            encountering a 429 error.
          schema:
            type: integer
        X-Envoy-Ratelimited:
          description: Indicating that you've been ratelimited
          schema:
            type: boolean
    RecipientsDataErasure500:
      description: Internal Server Error
      headers:
        X-RateLimit-Limit:
          description: The number of requests allowed during the  window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The amount of time (in seconds) until the current window is
            over and the limit is reset
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of request remaining in the 60-second window before
            encountering a 429 error.
          schema:
            type: integer
      content:
        application/json:
          schema:
            title: Internal Server Error
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/RecipientsDataErasureErrorV1'
            required:
            - errors
          example:
            errors:
            - message: Internal Server Error
              field: ''
  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>`). 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
  examples: {}
  requestBodies: {}
  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: Point Delete System
  description: Twilio SendGrid Recipients' Data Erasure API
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid