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.
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:
- [email protected]
- [email protected]
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:
- [email protected]
- [email protected]
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 [email protected] 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