{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Verified Senders API", "summary": "The Twilio SendGrid Verified Senders API allows you to programmatically manage the Sender Identities that are authorized to send email for your account.", "description": "The Twilio SendGrid Verified Senders API allows you to programmatically manage the Sender Identities that are authorized to send email for your account. You can also manage Sender Identities in the [SendGrid application user interface](https://app.sendgrid.com/settings/sender_auth). See [**Single Sender Verification**](https://sendgrid.com/docs/ui/sending-email/sender-verification/) for more information.\n\nYou an use this API to create new Sender Identities, retrieve a list of existing Sender Identities, check the status of a Sender Identity, update a Sender Identity, and delete a Sender Identity.\n\nThis API offers additional operations to check for domains known to implement DMARC and resend verification emails to Sender Identities that have yet to complete the verification process.", "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": "verified_senders" } }, "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/verified_senders": { "post": { "operationId": "CreateVerifiedSender", "summary": "Create Verified Sender Request", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to create a new Sender Identify**.\n\nUpon successful submission of a `POST` request to this endpoint, an identity will be created, and a verification email will be sent to the address assigned to the `from_email` field. You must complete the verification process using the sent email to fully verify the sender.\n\nIf you need to resend the verification email, you can do so with the Resend Verified Sender Request, `/resend/{id}`, endpoint.\n\nIf you need to authenticate a domain rather than a Single Sender, see the [Domain Authentication API](https://docs.sendgrid.com/api-reference/domain-authentication/authenticate-a-domain).", "requestBody": { "$ref": "#/components/requestBodies/PostPatchVerifiedSender" }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedSenderResponse" }, "examples": { "response": { "value": { "id": 1234, "nickname": "Example Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "$ref": "#/components/responses/VerifiedSenders403" }, "404": { "$ref": "#/components/responses/VerifiedSenders404" }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } }, "get": { "operationId": "ListVerifiedSender", "summary": "Get All Verified Senders", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to retrieve all the Sender Identities associated with an account.**\n\nThis endpoint will return both verified and unverified senders.\n\nYou can limit the number of results returned using the `limit`, `lastSeenID`, and `id` query string parameters.\n\n* `limit` allows you to specify an exact number of Sender Identities to return.\n* `lastSeenID` will return senders with an ID number occuring after the passed in ID. In other words, the `lastSeenID` provides a starting point from which SendGrid will iterate to find Sender Identities associated with your account.\n* `id` will return information about only the Sender Identity passed in the request.", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the number of results to be returned by the API. This parameter can be used to limit the results returned or in combination with the `lastSeenID` parameter to iterate through paginated results.", "schema": { "type": "number" } }, { "name": "lastSeenID", "in": "query", "description": "Returns senders with an ID number occurring after the passed in ID. In other words, the `lastSeenID` provides a starting point from which SendGrid will iterate to find Sender Identities associated with your account.", "schema": { "type": "number" } }, { "name": "id", "in": "query", "description": "Returns information about only the Sender Identity passed in the request.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/VerifiedSenderResponse" } } } }, "examples": { "response": { "value": { "results": [ { "id": 1234, "nickname": "Example Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false }, { "id": 1235, "nickname": "Example Support", "from_email": "support@example.com", "from_name": "Example Support", "reply_to": "support@example.com", "reply_to_name": "Example Support", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false } ] } } } } } }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "$ref": "#/components/responses/VerifiedSenders403" }, "404": { "$ref": "#/components/responses/VerifiedSenders404" }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } } }, "/v3/verified_senders/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "UpdateVerifiedSender", "summary": "Edit Verified Sender", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to update an existing Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint as a path parameter. Include any fields you wish to update in the request body in JSON format.\n\nYou can retrieve the IDs associated with Sender Identities by passing a `GET` request to the Get All Verified Senders endpoint, `/verified_senders`.\n\n**Note:** Unlike a `PUT` request, `PATCH` allows you to update only the fields you wish to edit. Fields that are not passed as part of a request will remain unaltered.", "requestBody": { "$ref": "#/components/requestBodies/PostPatchVerifiedSender" }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedSenderResponse" }, "examples": { "response": { "value": { "id": 1234, "nickname": "Example Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } }, "delete": { "operationId": "DeleteVerifiedSender", "summary": "Delete Verified Sender", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to delete a Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint to delete the Sender Identity from your account.\n\nYou can retrieve the IDs associated with Sender Identities using the \"Get All Verified Senders\" endpoint.", "responses": { "204": { "description": "" }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } } }, "/v3/verified_senders/domains": { "get": { "operationId": "ListVerifiedSenderDomain", "summary": "Domain Warn List", "tags": [ "Sender Verification" ], "description": "**This endpoint returns a list of domains known to implement DMARC and categorizes them by failure type \u2014 hard failure or soft failure**.\n\nDomains listed as hard failures will not deliver mail when used as a [Sender Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) due to the domain's DMARC policy settings.\n\nFor example, using a `yahoo.com` email address as a Sender Identity will likely result in the rejection of your mail. For more information about DMARC, see [Everything about DMARC](https://sendgrid.com/docs/ui/sending-email/dmarc/).", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "object", "required": [ "soft_failures", "hard_failures" ], "properties": { "soft_failures": { "type": "array", "items": { "type": "string" } }, "hard_failures": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "results" ] }, "examples": { "response": { "value": { "results": { "soft_failures": [ "gmail.com" ], "hard_failures": [ "yahoo.com" ] } } } } } } }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "$ref": "#/components/responses/VerifiedSenders403" }, "404": { "$ref": "#/components/responses/VerifiedSenders404" }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } } }, "/v3/verified_senders/resend/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "ResendVerifiedSender", "summary": "Resend Verified Sender Request", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to resend a verification email to a specified Sender Identity**.\n\nPassing the `id` assigned to a Sender Identity to this endpoint will resend a verification email to the `from_address` associated with the Sender Identity. This can be useful if someone loses their verification email or needs to have it resent for any other reason.\n\nYou can retrieve the IDs associated with Sender Identities by passing a \"Get All Verified Senders\" endpoint.", "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "$ref": "#/components/responses/VerifiedSenders403" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } } }, "/v3/verified_senders/steps_completed": { "get": { "operationId": "ListVerifiedSenderStepsCompleted", "summary": "Completed Steps", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to determine which of SendGrid\u2019s verification processes have been completed for an account**.\n\nThis endpoint returns boolean values, `true` and `false`, for [Domain Authentication](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#domain-authentication), `domain_verified`, and [Single Sender Verification](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#single-sender-verification), `sender_verified`, for the account.\n\nAn account may have one, both, or neither verification steps completed. If you need to authenticate a domain rather than a Single Sender, see the \"Authenticate a domain\" endpoint.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "object", "properties": { "sender_verified": { "type": "boolean" }, "domain_verified": { "type": "boolean" } } } } }, "examples": { "response": { "value": { "results": { "domain_verified": true, "sender_verified": true } } } } } } }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "$ref": "#/components/responses/VerifiedSenders403" }, "404": { "$ref": "#/components/responses/VerifiedSenders404" }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } } }, "/v3/verified_senders/verify/{token}": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "VerifySenderToken", "summary": "Verify Sender Request", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to verify a sender requests.**\n\nThe token is generated by SendGrid and included in a verification email delivered to the address that's pending verification.", "responses": { "204": { "description": "" }, "401": { "$ref": "#/components/responses/VerifiedSenders401" }, "403": { "$ref": "#/components/responses/VerifiedSenders403" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } } } }, "500": { "$ref": "#/components/responses/VerifiedSenders500" } } } } }, "components": { "schemas": { "VerifiedSenderRequest": { "title": "Verified Sender Request Schema", "type": "object", "properties": { "nickname": { "type": "string", "maxLength": 100 }, "from_email": { "type": "string", "maxLength": 256, "format": "email" }, "from_name": { "type": "string", "maxLength": 256 }, "reply_to": { "type": "string", "maxLength": 256, "format": "email" }, "reply_to_name": { "type": "string", "maxLength": 256 }, "address": { "type": "string", "maxLength": 100 }, "address2": { "type": "string", "maxLength": 100 }, "state": { "type": "string", "maxLength": 2 }, "city": { "type": "string", "maxLength": 150 }, "zip": { "type": "string", "maxLength": 10 }, "country": { "type": "string", "maxLength": 100 } }, "required": [ "nickname", "from_email", "reply_to" ], "example": { "nickname": "Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105" } }, "VerifiedSenderResponse": { "title": "Verified Sender Response Schema", "type": "object", "properties": { "id": { "type": "integer" }, "nickname": { "type": "string" }, "from_email": { "type": "string" }, "from_name": { "type": "string" }, "reply_to": { "type": "string" }, "reply_to_name": { "type": "string" }, "address": { "type": "string" }, "address2": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "verified": { "type": "boolean" }, "locked": { "type": "boolean" } }, "example": { "id": 1234, "nickname": "Example Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false } }, "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" } ] } } }, "responses": { "VerifiedSenders401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "VerifiedSenders403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "VerifiedSenders404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "VerifiedSenders500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } }, "parameters": {}, "examples": {}, "requestBodies": { "PostPatchVerifiedSender": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedSenderRequest" } } } } }, "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": "Sender Verification", "description": "Twilio SendGrid Sender Verification API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }