{ "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.\n\nYou 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.\n\nSendGrid 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.\n\nSee [**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.**\n\nTo 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.**\n\nThis 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.**\n\nIf 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.\n\nDeleting 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.**\n\nIf 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": [ "test1@example.com", "test2@example.com" ] } } } } } } } }, "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": [ "example@example.com", "example2@example.com" ] } } } } } } } }, "/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.**\n\nRemoving 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.**\n\nWhen 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": [ "exists1@example.com", "exists2@example.com" ] } } } } } } } }, "/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": "test1@example.com", "group_id": 1, "group_name": "Weekly News", "created_at": 1410986704 }, { "email": "test1@example.com", "group_id": 2, "group_name": "Daily News", "created_at": 1411493671 }, { "email": "test2@example.com", "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.**\n\nYou 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": "example@example.com", "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", "status": "4.0.0" }, { "created": 1443651155, "email": "example1@example.com", "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\n1. 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": [ "example1@example.com", "example2@example.com" ] } } } } }, "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": "example@example.com", "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.**\n\nYou 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": "example@example.com", "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": "example@example.com", "reason": "550 5.1.1 : 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": "bounce1@test.com", "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", "properties": { "classification": { "type": "string", "$ref": "#/components/schemas/Classification" }, "count": { "type": "integer" } } } } } } } } }, "examples": { "response": { "value": { "result": [ { "date": "2022-01-01", "stats": [ { "classification": "Unclassified", "count": 35 }, { "classification": "Invalid Address", "count": 14 } ] }, { "date": "2022-01-02", "stats": [ { "classification": "Unclassified", "count": 23 }, { "classification": "Content", "count": 4 } ] } ] } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v3/suppression/bounces/classifications/{classification}": { "get": { "operationId": "GetSuppressionBouncesClassifications", "summary": "Retrieve bounce classification over time by domain stats", "tags": [ "Bounces" ], "description": "This endpoint will return the number of bounces for the classification specified 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": { "type": "string", "default": "application/json", "$ref": "#/components/schemas/Accept1" } }, { "name": "classification", "in": "path", "description": "The classification you want to filter by. Possible values are: `Content`, `Frequency or Volume Too High`, `Invalid Address`, `Mailbox Unavailable`, `Reputation`, `Technical Failure`, `Unclassified`.", "schema": { "type": "string", "$ref": "#/components/schemas/Classification1" }, "required": true }, { "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": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "stats": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "count": { "type": "integer" } } } } } } } } }, "examples": { "response": { "value": { "result": [ { "date": "2022-01-01", "stats": [ { "domain": "example.com", "count": 35 }, { "domain": "one.example.com", "count": 14 } ] }, { "date": "2022-01-02", "stats": [ { "domain": "example.com", "count": 23 }, { "domain": "one.example.com", "count": 4 } ] } ] } } } } } } } } }, "/v3/asm/suppressions/global": { "post": { "operationId": "CreateGlobalSuppression", "summary": "Add recipient addresses to the global suppression group.", "tags": [ "Global Suppressions" ], "description": "**This endpoint allows you to add one or more email addresses to the global suppressions group.**", "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 that are globally suppressed", "items": { "type": "string", "format": "email" } } }, "required": [ "recipient_emails" ] }, "examples": { "response": { "value": { "recipient_emails": [ "test1@example.com", "test2@example.com" ] } } } } } } } } }, "/v3/asm/suppressions/global/{email}": { "parameters": [ { "name": "email", "in": "path", "description": "The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetGlobalSuppression", "summary": "Retrieve a Global Suppression", "tags": [ "Global Suppressions" ], "description": "**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**\n\nIf the email address you include in the URL path parameter `{email}` is already globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "title": "Retrieve a Global Suppression response", "type": "object", "properties": { "recipient_email": { "type": "string", "description": "The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed.", "format": "email" } }, "required": [ "recipient_email" ] }, "examples": { "response": { "value": { "recipient_email": "test@example.com" } } } } } } } }, "delete": { "operationId": "DeleteGlobalSuppression", "summary": "Delete a Global Suppression", "tags": [ "Global Suppressions" ], "description": "**This endpoint allows you to remove an email address from the global suppressions group.**\n\nDeleting 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/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.**\n\nYou 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.**\n\nThere are two options for deleting invalid email addresses: \n\n1) You can delete all invalid email addresses by setting `delete_all` to true in the request body.\n2) 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": "" } } } }, "/v3/suppression/spam_reports": { "get": { "operationId": "ListSpamReport", "summary": "Retrieve all spam reports", "tags": [ "Spam Reports" ], "description": "**This endpoint allows you to retrieve a paginated list of all spam reports.**\n\nYou 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 spam report 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 spam report 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/SpamReportsResponse" }, "examples": { "response": { "value": [ { "created": 1443651141, "email": "user1@example.com", "ip": "10.63.202.100" }, { "created": 1443651154, "email": "user2@example.com", "ip": "10.63.202.100" } ] } } } } } } }, "delete": { "operationId": "DeleteSpamReports", "summary": "Delete spam reports", "tags": [ "Spam Reports" ], "description": "**This endpoint allows you to delete your spam reports.**\n\nDeleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. 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.\n\nThere are two options for deleting spam reports: \n\n1. You can delete all spam reports by setting the `delete_all` field to `true` in the request body.\n2. You can delete a list of select spam reports 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 email addresses on the spam report list." }, "emails": { "type": "array", "description": "A list of specific email addresses that you want to remove from the spam report list.", "items": { "type": "string" } } }, "example": { "delete_all": false, "emails": [ "example1@example.com", "example2@example.com" ] } } } } }, "responses": { "204": { "description": "" } } } }, "/v3/suppression/spam_reports/{email}": { "parameters": [ { "name": "email", "in": "path", "description": "The email address of a specific spam report that you want to retrieve.", "required": true, "schema": { "type": "string", "format": "email" } } ], "get": { "operationId": "GetSpamReport", "summary": "Retrieve a specific spam report", "tags": [ "Spam Reports" ], "description": "**This endpoint allows you to retrieve a specific spam report by email address.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpamReportsResponse" }, "examples": { "response": { "value": [ { "created": 1454433146, "email": "test1@example.com", "ip": "10.89.32.5" } ] } } } } } } }, "delete": { "operationId": "DeleteSpamReport", "summary": "Delete a specific spam report", "tags": [ "Spam Reports" ], "description": "**This endpoint allows you to delete a specific spam report by email address.**\n\nDeleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. 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/suppression/unsubscribes": { "get": { "operationId": "ListGlobalSuppression", "summary": "Retrieve all global suppressions", "tags": [ "Global Suppressions" ], "description": "**This endpoint allows you to retrieve a paginated list of all email address that are globally suppressed.**\n\nYou 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 unsubscribe email was created (inclusive).", "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive).", "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": { "type": "array", "items": { "type": "object", "properties": { "created": { "type": "integer", "description": "A Unix timestamp indicating when the recipient was added to the global suppression list." }, "email": { "type": "string", "description": "The email address of the recipient who is globally suppressed.", "format": "email" } }, "required": [ "created", "email" ] } }, "examples": { "response": { "value": [ { "created": 1443651141, "email": "user1@example.com" }, { "created": 1443651154, "email": "user2@example.com" } ] } } } } } } } } }, "components": { "schemas": { "SuppressionGroup": { "title": "Suppressions: Suppression Group", "type": "object", "properties": { "id": { "type": "number", "description": "The id of the suppression group." }, "name": { "type": "string", "description": "The name of the suppression group. Each group created by a user must have a unique name.", "maxLength": 30 }, "description": { "type": "string", "description": "A description of the suppression group.", "maxLength": 100 }, "is_default": { "type": "boolean", "default": false, "description": "Indicates if this is the default suppression group." }, "unsubscribes": { "type": "integer", "description": "The unsubscribes associated with this group." } }, "required": [ "id", "name", "description" ] }, "SuppressionGroupRequestBaseProps": { "title": "Suppression Group Request Base", "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." } } }, "SuppressionsRequest": { "title": "Suppressions Request Body", "type": "object", "properties": { "recipient_emails": { "type": "array", "description": "The array of email addresses to add or find.", "items": { "type": "string", "format": "email" } } }, "required": [ "recipient_emails" ], "example": { "recipient_emails": [ "test1@example.com", "test2@example.com" ] } }, "SpamReportsResponse": { "title": "Spam Reports Response", "type": "array", "items": { "type": "object", "properties": { "created": { "type": "integer", "description": "A Unix timestamp that indicates when the recipient marked your message as spam." }, "email": { "type": "string", "description": "The email address of the recipient that marked your message as spam.", "format": "email" }, "ip": { "type": "string", "description": "The IP address that the message was sent from." } }, "required": [ "created", "email", "ip" ] }, "example": [ { "created": 1443651141, "email": "user1@example.com", "ip": "10.63.202.100" }, { "created": 1443651154, "email": "user2@example.com", "ip": "10.63.202.100" } ] }, "BlocksResponse": { "title": "Blocks Response", "type": "array", "items": { "type": "object", "properties": { "created": { "type": "integer", "description": "A Unix timestamp indicating when the email address was added to the blocks list." }, "email": { "type": "string", "description": "The email address that was added to the block list.", "format": "email" }, "reason": { "type": "string", "description": "An explanation for the reason of the block." }, "status": { "type": "string", "description": "The status of the block." } }, "required": [ "created", "email", "reason", "status" ] }, "example": [ { "created": 1443651154, "email": "example@example.com", "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", "status": "4.0.0" } ] }, "BounceResponse": { "title": "Bounce Response", "type": "object", "properties": { "created": { "type": "number", "description": "The unix timestamp for when the bounce record was created at SendGrid." }, "email": { "type": "string", "format": "email", "description": "The email address that was added to the bounce list." }, "reason": { "type": "string", "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." }, "status": { "type": "string", "description": "Enhanced SMTP bounce response" } }, "example": { "created": 1250337600, "email": "example@example.com", "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" } }, "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" } }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "An error message." }, "field": { "description": "When applicable, this property value will be the field that generated the error.", "nullable": true, "type": "string" }, "help": { "type": "object", "description": "When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error." } } } }, "id": { "type": "string", "description": "When applicable, this property value will be an error ID." } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } }, "Accept": { "type": "string", "enum": [ "application/json", "text/csv" ] }, "Classification": { "type": "string", "enum": [ "Content", "Frequency or Volume Too High", "Invalid Address", "Mailbox Unavailable", "Reputation", "Technical Failure", "Unclassified" ] }, "Accept1": { "type": "string", "enum": [ "application/json", "text/csv" ] }, "Classification1": { "type": "string", "enum": [ "Content", "Frequency or Volume Too High", "Invalid Address", "Mailbox Unavailable", "Reputation", "Technical Failure", "Unclassified" ] } }, "responses": {}, "parameters": { "EmailPartialMatch": { "name": "email", "in": "query", "description": "Specifies which records to return based on the records' associated email addresses. For example, `sales` returns records with email addresses that start with 'sales', such as `salesdepartment@example.com` or `sales@example.com`. You can also use `%25` as a wildcard. For example, `%25market` returns records containing email addresses with the string 'market' anywhere in the email address, and `%25market%25tree` returns records containing email addresses with the string 'market' followed by the string 'tree'. Any reserved characters should be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding#Reserved_characters), e.g., the `@` symbol should be encoded as `%40`.", "required": false, "schema": { "type": "string" } }, "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 `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). 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 } }, "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 } } }, "examples": {}, "requestBodies": { "PostSuppressions": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionsRequest" } } } } }, "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": "Suppressions", "description": "Twilio SendGrid Suppressions API" }, { "name": "Global Suppressions", "description": "Twilio SendGrid Suppressions API: Global Suppressions operations" }, { "name": "Unsubscribe Groups", "description": "Twilio SendGrid Suppressions API: Unsubscribe Group operations" }, { "name": "Blocks", "description": "Twilio SendGrid Suppressions API: Blocks operations" }, { "name": "Bounces", "description": "Twilio SendGrid Suppressions API: Bounces operations" }, { "name": "Invalid Emails", "description": "Twilio SendGrid Suppressions API: Invalid Emails operations" }, { "name": "Spam Reports", "description": "Twilio SendGrid Suppressions API: Spam Reports operations" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }