The Twilio SendGrid Suppressions API allows you to manage your Suppressions or Unsubscribes and Suppression or Unsubscribe groups. With SendGrid, an unsubscribe is the action an email recipient takes when they opt-out of receiving your messages. A suppression is the action you take as a sender to filter or suppress an unsubscribed address from your email send. From the perspective of the recipient, your suppression is the result of their unsubscribe.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Suppressions 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. With SendGrid, an unsubscribe
is the action an email recipient takes when they opt-out of receiving your messages.
A suppression is the action you take as a sender to filter or suppress an unsubscribed
address from your email send. From the perspective of the recipient, your suppression
is the result of their unsubscribe.
You can have global suppressions, which represent addresses that have been unsubscribed
from all of your emails. You can also have suppression groups, also known as ASM
groups, which represent categories or groups of emails that your recipients can
unsubscribe from, rather than unsubscribing from all of your messages.
SendGrid automatically suppresses emails sent to users for a variety of reasons,
including blocks, bounces, invalid email addresses, spam reports, and unsubscribes.
SendGrid suppresses these messages to help you maintain the best possible sender
reputation by attempting to prevent unwanted mail. You may also add addresses
to your suppressions.
See [**Suppressions**](https://docs.sendgrid.com/for-developers/sending-email/suppressions)
for more information.'
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
paths:
/v3/asm/groups:
post:
operationId: CreatAsmGroup
summary: Create a new suppression group
tags:
- Unsubscribe Groups
description: '**This endpoint allows you to create a new suppression group.**
To add an email address to the suppression group, [create a Suppression](https://docs.sendgrid.com/api-reference/suppressions-suppressions/add-suppressions-to-a-suppression-group).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SuppressionGroupRequestBaseProps'
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The ID of the suppression group.
name:
type: string
description: The name of the suppression group.
description:
type: string
description: A brief description of the suppression group.
is_default:
type: boolean
description: Indicates if this is the default suppression group.
required:
- id
- name
- description
- is_default
examples:
response:
value:
id: 103
name: Product Suggestions
description: Suggestions for products our users might like.
is_default: false
get:
operationId: ListAsmGroup
summary: Retrieve all suppression groups associated with the user.
tags:
- Unsubscribe Groups
description: '**This endpoint allows you to retrieve a list of all suppression
groups created by this user.**
This endpoint can also return information for multiple group IDs that you
include in your request. To add a group ID to your request, simply append
`?id=123456&id=123456`, with the appropriate group IDs.'
parameters:
- name: id
in: query
description: The ID of the suppression group(s) you want to retrieve.
schema:
type: integer
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SuppressionGroup'
examples:
response:
value:
- id: 1234
name: Unsubscribe Group
description: An Unsubscribe Group
is_default: true
unsubscribes: 1234
- id: 1234
name: Unsubscribe Group
description: An Unsubscribe Group
is_default: true
unsubscribes: 1234
/v3/asm/groups/{group_id}:
parameters:
- name: group_id
in: path
description: The ID of the suppression group you would like to retrieve.
required: true
schema:
type: string
get:
operationId: GetAsmGroup
summary: Get information on a single suppression group.
tags:
- Unsubscribe Groups
description: '**This endpoint allows you to retrieve a single suppression group.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of your suppression group. Required when
creating a group.
maxLength: 30
description:
type: string
description: A brief description of your suppression group. Required
when creating a group.
maxLength: 100
is_default:
type: boolean
description: Indicates if you would like this to be your default
suppression group.
id:
type: integer
description: The ID of the suppression group.
unsubscribes:
type: integer
description: The number of unsubscribes, or suppressions, in this
group.
required:
- id
examples:
response:
value:
description: Our monthly newsletter.
id: 100
is_default: true
name: Newsletters
unsubscribes: 400
patch:
operationId: UpdateAsmGroup
summary: Update a suppression group.
tags:
- Unsubscribe Groups
description: '**This endpoint allows you to update or change a suppression group.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
example:
id: 103
name: Item Suggestions
description: Suggestions for items our users might like.
type: object
properties:
name:
type: string
description: The name of your suppression group. Required when creating
a group.
maxLength: 30
description:
type: string
description: A brief description of your suppression group. Required
when creating a group.
maxLength: 100
is_default:
type: boolean
description: Indicates if you would like this to be your default
suppression group.
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SuppressionGroup'
examples:
response:
value:
id: 103
name: Item Suggestions
description: Suggestions for items our users might like.
delete:
operationId: DeleteAsmGroup
summary: Delete a Suppression Group
tags:
- Unsubscribe Groups
description: '**This endpoint allows you to delete a suppression group.**
If a recipient uses the "one-click unsubscribe" option on an email associated
with a deleted group, that recipient will be added to the global suppression
list.
Deleting a suppression group 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:
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:
- [email protected]
- [email protected]
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:
- [email protected]
- [email protected]
/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:
- [email protected]
- [email protected]
/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: [email protected]
group_id: 1
group_name: Weekly News
created_at: 1410986704
- email: [email protected]
group_id: 2
group_name: Daily News
created_at: 1411493671
- email: [email protected]
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
/v3/suppression/blocks:
get:
operationId: ListSuppressionBlock
summary: Retrieve all blocks
tags:
- Blocks
description: '**This endpoint allows you to retrieve a paginated list of all
email addresses that are currently on your blocks list.**
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: The start of the time range when a blocked email was created
(inclusive). This is a unix timestamp.
schema:
type: integer
- name: end_time
in: query
description: The end of the time range when a blocked email was created (inclusive).
This is a unix timestamp.
schema:
type: integer
- $ref: '#/components/parameters/PaginationCommonLimit'
- $ref: '#/components/parameters/PaginationCommonOffset'
- $ref: '#/components/parameters/EmailPartialMatch'
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlocksResponse'
examples:
response:
value:
- created: 1443651154
email: [email protected]
reason: 'error dialing remote address: dial tcp 10.57.152.165:25:
no route to host'
status: 4.0.0
- created: 1443651155
email: [email protected]
reason: 'unable to resolve MX record for example.com: servfail'
status: 4.0.0
delete:
operationId: DeleteSuppressionBlocks
summary: Delete blocks
tags:
- Blocks
description: "**This endpoint allows you to delete all email addresses on your\
\ blocks list.**\n\nThere are two options for deleting blocked emails: \n\n\
1. You can delete all blocked emails by setting `delete_all` to `true` in\
\ the request body. \n2. You can delete a selection of blocked emails by specifying\
\ the email addresses in the `emails` array of 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 delete all blocked email addresses.
emails:
type: array
description: The specific blocked email addresses that you want
to delete.
items:
type: string
example:
delete_all: false
emails:
- [email protected]
- [email protected]
responses:
'204':
description: ''
/v3/suppression/blocks/{email}:
parameters:
- name: email
in: path
description: The email address of the specific block.
required: true
schema:
type: string
format: email
get:
operationId: GetSuppressionBlock
summary: Retrieve a specific block
tags:
- Blocks
description: '**This endpoint allows you to retrieve a specific email address
from your blocks list.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlocksResponse'
examples:
response:
value:
- created: 1443651154
email: [email protected]
reason: 'error dialing remote address: dial tcp 10.57.152.165:25:
no route to host'
status: 4.0.0
delete:
operationId: DeleteSuppressionBlock
summary: Delete a specific block
tags:
- Blocks
description: '**This endpoint allows you to delete a specific email address
from your blocks list.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'204':
description: ''
/v3/suppression/bounces:
get:
operationId: ListSuppressionBounces
summary: Retrieve all bounces
tags:
- Bounces
description: '**This endpoint allows you to retrieve a paginated list of all
your bounces.**
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 a bounce
was created (inclusive).
schema:
type: integer
- name: end_time
in: query
description: Refers end of the time range in unix timestamp when a bounce
was created (inclusive).
schema:
type: integer
- $ref: '#/components/parameters/PaginationCommonLimit'
- $ref: '#/components/parameters/PaginationCommonOffset'
- name: Accept
in: header
required: true
schema:
type: string
default: application/json
- $ref: '#/components/parameters/EmailPartialMatch'
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BounceResponse'
examples:
response:
value:
- created: 1250337600
email: [email protected]
reason: '550 5.1.1 The email account that you tried to reach does
not exist. Please try double-checking the recipient''s email
address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596
o186si2389584ioe.63 - gsmtp '
status: 5.1.1
- created: 1250337600
email: [email protected]
reason: '550 5.1.1 <[email protected]>: Recipient address
rejected: User unknown in virtual alias table '
status: 5.1.1
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
operationId: DeleteSuppressionBounces
summary: Delete bounces
tags:
- Bounces
description: "**This endpoint allows you to delete all emails on your bounces\
\ list.**\n\nThere are two options for deleting bounced emails: \n\n1. You\
\ can delete all bounced emails by setting `delete_all` to `true` in the request\
\ body. \n2. You can delete a selection of bounced emails by specifying the\
\ email addresses in the `emails` array of the request body. \n\n**WARNING:**\
\ You can not have both `emails` and `delete_all` set."
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
delete_all:
type: boolean
description: This parameter allows you to delete **every** email
in your bounce list. This should not be used with the emails parameter.
emails:
type: array
description: Delete multiple emails from your bounce list at the
same time. This should not be used with the delete_all parameter.
items:
type: string
example:
delete_all: false
responses:
'204':
description: ''
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: authorization required
/v3/suppression/bounces/{email}:
get:
operationId: GetSuppressionBounces
summary: Retrieve a Bounce
tags:
- Bounces
description: '**This endpoint allows you to retrieve a specific bounce by email
address.**'
parameters:
- name: email
in: path
description: The email address of the specific bounce you would like to retrieve
required: true
schema:
type: string
format: email
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BounceResponse'
examples:
response:
value:
- created: 1443651125
email: [email protected]
reason: '550 5.1.1 The email account that you tried to reach does
not exist. Please try double-checking the recipient''s email
address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596
o186si2389584ioe.63 - gsmtp '
status: 5.1.1
delete:
operationId: DeleteSuppressionBounce
summary: Delete a bounce
tags:
- Bounces
description: '**This endpoint allows you to remove an email address from your
bounce list.**'
parameters:
- name: email
in: path
description: The email address you would like to remove from the bounce list.
required: true
schema:
type: string
format: email
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'204':
description: ''
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: authorization required
/v3/suppression/bounces/classifications:
get:
operationId: ListSuppressionBouncesClassifications
summary: Retrieve bounce classification totals
tags:
- Bounces
description: This endpoint will return the total number of bounces by classification
in descending order for each day. You can retrieve the bounce classification
totals in CSV format by specifying `"text/csv"` in the Accept header.
parameters:
- name: Accept
in: header
description: Specifies the content type to be returned by this endpoint. You
can choose to receive CSV-formatted data by passing "text/csv" in the header.
required: true
schema:
default: application/json
type: string
$ref: '#/components/schemas/Accept'
- name: start_date
in: query
description: The start of the time range, in YYYY-MM-DD format, when a bounce
was created (inclusive).
schema:
type: string
- name: end_date
in: query
description: The end of the time range, in YYYY-MM-DD format, when a bounce
was created (inclusive).
schema:
type: string
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
type: object
properties:
date:
type: string
stats:
type: array
items:
type: object
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_suppressions_v3.yaml