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.
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.
You 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.
This 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**.
Upon 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.
If you need to resend the verification email, you can do so with the Resend
Verified Sender Request, `/resend/{id}`, endpoint.
If 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: [email protected]
from_name: Example Orders
reply_to: [email protected]
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.**
This endpoint will return both verified and unverified senders.
You can limit the number of results returned using the `limit`, `lastSeenID`,
and `id` query string parameters.
* `limit` allows you to specify an exact number of Sender Identities to return.
* `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.
* `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: [email protected]
from_name: Example Orders
reply_to: [email protected]
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: [email protected]
from_name: Example Support
reply_to: [email protected]
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**.
Pass 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.
You can retrieve the IDs associated with Sender Identities by passing a `GET`
request to the Get All Verified Senders endpoint, `/verified_senders`.
**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: [email protected]
from_name: Example Orders
reply_to: [email protected]
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**.
Pass the `id` assigned to a Sender Identity to this endpoint to delete the
Sender Identity from your account.
You 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**.
Passing 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.
You 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\u2019\
s 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.**
The 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: [email protected]
from_name: Example Orders
reply_to: [email protected]
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: [email protected]
from_name: Example Orders
reply_to: [email protected]
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