SendGrid Point Delete System API

openapi: 3.2.0
info:
  title: Twilio SendGrid Recipients' Data Erasure Point Delete…
  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
security:
- BearerAuth: []
tags:
- name: Point Delete System
  description: Twilio SendGrid Recipients' Data Erasure API
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**


        The 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.


        All email addresses are filtered for uniqueness and tested for structural validity—any invalid addresses will be returned in an error response.


        Please note that recipient data is deleted for the account making the request only—deletions 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:
    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
    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
  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
  responses:
    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
    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: ''
    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
    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: ''
    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: ''
    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: ''
  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