The Twilio SendGrid v3 Mail API allows you to send email at scale over HTTP. The Mail Send endpoint supports many levels of functionality, allowing you to send templates, set categories and custom arguments that can be used to analyze your send, and configure which tracking settings to include such as opens and clicks. You can also group mail sends into batches, allowing you to schedule and cancel sends by their batch IDs.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Mail API
summary: The Twilio SendGrid v3 Mail API allows you to send email at scale over
HTTP. You can also group mail sends into batches.
description: The Twilio SendGrid v3 Mail API allows you to send email at scale over
HTTP. The Mail Send endpoint supports many levels of functionality, allowing you
to send templates, set categories and custom arguments that can be used to analyze
your send, and configure which tracking settings to include such as opens and
clicks. You can also group mail sends into batches, allowing you to schedule and
cancel sends by their batch IDs.
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: mail
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/mail/batch:
post:
tags:
- Mail Batch
summary: Create a batch ID.
description: '**This operation allows you to generate a new mail batch ID.**
Once a batch ID is created, you can associate it with a mail send by passing
it in the request body of the [Mail Send operation](https://docs.sendgrid.com/api-reference/mail-send/mail-send).
This makes it possible to group multiple requests to the Mail Send operation
by assigning them the same batch ID.
A batch ID that''s associated with a mail send can be used to access and modify
the associated send. For example, you can pause or cancel a send using its
batch ID. See the [Scheduled Sends API](https://www.twilio.com/docs/sendgrid/api-reference/cancel-scheduled-sends)
for more information about pausing and cancelling a mail send.
'
operationId: CreateMailBatch
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'201':
$ref: '#/components/responses/MailBatch2xx'
'400':
$ref: '#/components/responses/MailBatch400'
'401':
$ref: '#/components/responses/MailBatch401'
'403':
$ref: '#/components/responses/MailBatch403'
'404':
$ref: '#/components/responses/MailBatch404'
'405':
$ref: '#/components/responses/MailBatch405'
'500':
$ref: '#/components/responses/MailBatch500'
/v3/mail/batch/{batch_id}:
parameters:
- $ref: '#/components/parameters/BatchId'
get:
tags:
- Mail Batch
summary: Validate a batch ID.
description: '**This operation allows you to validate a mail batch ID.**
If you provide a valid batch ID, this operation will return a `200` status
code and the batch ID itself.
If you provide an invalid batch ID, you will receive a `400` level status
code and an error message.
A batch ID does not need to be assigned to a send to be considered valid.
A successful response means only that the batch ID has been created, but it
does not indicate that the ID has been assigned to a send.'
operationId: GetMailBatch
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
$ref: '#/components/responses/MailBatch2xx'
'400':
$ref: '#/components/responses/MailBatch400'
'401':
$ref: '#/components/responses/MailBatch401'
'403':
$ref: '#/components/responses/MailBatch403'
'405':
$ref: '#/components/responses/MailBatch405'
'500':
$ref: '#/components/responses/MailBatch500'
/v3/mail/send:
post:
tags:
- Mail Send
summary: Send Email with Twilio SendGrid.
description: '*The Mail Send operation allows you to send email over SendGrid''s
v3 Web API*
For an overview of this API, including its features and limitations, please
see the [Mail Send API overview page](https://www.twilio.com/docs/sendgrid/api-reference/mail-send)
The overview page also includes links to SendGrid''s Email API quickstarts
and helper libraries to get you working with this endpoint even faster.
'
operationId: SendMail
parameters:
- $ref: '#/components/parameters/MailBodyCompression'
requestBody:
$ref: '#/components/requestBodies/PostMailSend'
responses:
'202':
description: Accepted
'400':
$ref: '#/components/responses/PostMailSend400'
'401':
$ref: '#/components/responses/PostMailSend401'
'403':
$ref: '#/components/responses/PostMailSend403'
'404':
$ref: '#/components/responses/PostMailSend404'
'405':
$ref: '#/components/responses/PostMailSend405'
'413':
$ref: '#/components/responses/PostMailSend413'
'500':
$ref: '#/components/responses/PostMailSend500'
components:
schemas:
MailFrom:
title: From Email Object
type: object
properties:
email:
type: string
format: email
description: The email address from which messages are sent. This address
should be a verified sender in your Twilio SendGrid account. Email addresses
specified in `personalizations` will override addresses set at the message
level outside of the `personalizations` object.
name:
type: string
description: A name or title associated with the email address such as "Support"
or "Alex".
required:
- email
MailTo:
title: To Email Object
type: object
properties:
email:
type: string
format: email
description: An email address to which a message is sent. Email addresses
specified in `personalizations` will override addresses set at the message
level outside of the `personalizations` object.
name:
type: string
description: A name or title associated with the email address such as "Alex".
required:
- email
MailBatchResponse:
title: Mail Batch and Batch ID Response Schema
type: object
properties:
batch_id:
type: string
description: A mail batch ID.
example:
batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi
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
ContentEncoding:
type: string
enum:
- gzip
Disposition:
type: string
enum:
- inline
- attachment
responses:
PostMailSend400:
description: Mail Send bad response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: invalid request
field: 'null'
PostMailSend401:
description: Mail Send unauthorized response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: authorization required
field: 'null'
PostMailSend403:
description: Mail Send forbidden response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: access forbidden
field: 'null'
PostMailSend404:
description: Mail Send not found response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: not found
field: 'null'
PostMailSend405:
description: Mail Send method not allowed response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: method not allowed
field: 'null'
PostMailSend413:
description: Mail Send content too large response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: content too large
field: 'null'
PostMailSend500:
description: Mail send internal server error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: internal server error
MailBatch2xx:
description: Batch ID success response.
content:
application/json:
schema:
$ref: '#/components/schemas/MailBatchResponse'
examples:
Success:
$ref: '#/components/examples/MailBatch2xx'
MailBatch400:
description: Batch ID bad response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Bad request:
value:
errors:
- message: invalid batch id
field: 'null'
MailBatch401:
description: Batch ID unauthorized response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: authorization required
field: 'null'
MailBatch403:
description: Batch ID forbidden response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: access forbidden
field: 'null'
MailBatch404:
description: Batch ID not found response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: batch id not found
field: 'null'
MailBatch405:
description: Get batch ID method not allowed response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: method not allowed
field: 'null'
MailBatch500:
description: Get batch ID internal server error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: internal server error
field: 'null'
parameters:
OnBehalfOf:
name: on-behalf-of
in: header
description: Use the `on-behalf-of` header to make API calls for a particular
Subuser through the parent account. You can use this header to automate bulk
updates or to administer a Subuser without changing the authentication in
your code. You will use the parent account's API key when using this header.
required: false
schema:
type: string
BatchId:
name: batch_id
in: path
description: Set this parameter to the batch ID that's associated with the mail
send you want to retrieve.
required: true
schema:
type: string
MailBodyCompression:
name: Content-Encoding
in: header
description: Use this header when sending a gzip compressed mail body. Mail
body compression is available to some high volume accounts. Submit a [request
to support](https://support.sendgrid.com/hc/en-us) to have gzip enabled on
your account.
required: false
schema:
type: string
$ref: '#/components/schemas/ContentEncoding'
examples:
MailBatch2xx:
summary: A mail batch ID.
value:
batch_id: 123abc456def789hij0
requestBodies:
PostMailSend:
content:
application/json:
schema:
type: object
properties:
personalizations:
type: array
description: "An array of messages and their metadata. Each object\
\ within the `personalizations` array can be thought of as a mail\
\ envelope\u2014it defines who should receive an individual message\
\ and how that message should be handled. See [**Personalizations**](https://sendgrid.com/docs/for-developers/sending-email/personalizations/)\
\ for more information."
uniqueItems: false
maxItems: 1000
items:
type: object
properties:
from:
$ref: '#/components/schemas/MailFrom'
to:
type: array
description: An array of recipients to whom the email will be
sent. Each object in this array must contain a recipient's
email address. Each object in the array may optionally contain
a recipient's name.
items:
$ref: '#/components/schemas/MailTo'
cc:
type: array
description: An array of recipients to whom a copy of the email
will be sent. Each object in this array must contain a recipient's
email address. Each object in the array may optionally contain
a recipient's name.
maxItems: 1000
items:
$ref: '#/components/schemas/MailTo'
bcc:
type: array
description: An array of recipients to whom a blind carbon copy
of your email will be sent. Each object in this array must
contain a recipient's email address. Each object in the array
may optionally contain a recipient's name.
maxItems: 1000
items:
$ref: '#/components/schemas/MailTo'
subject:
type: string
description: The subject of your email. See line length limits
specified in [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822#section-2.1.1)
for guidance on subject line character limits.
minLength: 1
headers:
type: object
description: 'A collection of JSON property name and property
value pairs allowing you to specify handling instructions
for your email. You may not override the following headers:
`x-sg-id`, `x-sg-eid`, `received`, `dkim-signature`, `Content-Type`,
`Content-Transfer-Encoding`, `To`, `From`, `Subject`, `Reply-To`,
`CC`, `BCC`.'
substitutions:
type: object
description: A collection property names that will be substituted
by their corresponding property values in the `subject`, `reply-to`
and `content` portions of your message. Name and value pairs
follow the pattern `"substitution_tag":"value to substitute"`.
The total collective size of your substitutions may not exceed
10,000 bytes per personalization object. Substitutions allow
you to insert data without using SendGrid's Dynamic Templates.
This property should not be used in combination with a Dynamic
Template, which can be identified by a `template_id` starting
with `d-`. See [**Substitution Tags**](https://docs.sendgrid.com/for-developers/sending-email/substitution-tags)
for more information.
maxProperties: 10000
additionalProperties:
type: string
dynamic_template_data:
type: object
description: A collection property names that will be substituted
by their corresponding property values in the `subject`, `reply-to`
and `content` portions of a SendGrid Dynamic Template. Dynamic
template data is available in a template using [Handlebars](https://docs.sendgrid.com/for-developers/sending-email/using-handlebars)
syntax. This property should be used in combination with a
Dynamic Template, which can be identified by a `template_id`
starting with `d-`. See [**How to Send an Email with Dynamic
Templates**](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates)
for more information.
custom_args:
type: object
description: Values that are specific to this personalization
that will be carried along with the email and its activity
data. Substitutions will not be made on custom arguments,
so any string that is assigned to this property will be assumed
to be the custom argument that you would like to be used.
This field may not exceed 10,000 bytes.
maxProperties: 10000
send_at:
type: integer
description: A [unix timestamp](https://en.wikipedia.org/wiki/Unix_time)
allowing you to specify when your email should be sent. A
send cannot be scheduled more than 72 hours in advance.
required:
- to
from:
$ref: '#/components/schemas/MailFrom'
reply_to:
$ref: '#/components/schemas/MailTo'
reply_to_list:
type: array
description: An array of recipients to whom replies will be sent.
Each object in this array must contain a recipient's email address.
Each object in the array may optionally contain a recipient's name.
You can use either the `reply_to` property or `reply_to_list` property
but not both.
uniqueItems: true
maxItems: 1000
items:
$ref: '#/components/schemas/MailTo'
subject:
type: string
description: The global or _message level_ subject of your email.
Subject lines set in personalizations objects will override this
global subject line. See line length limits specified in [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822#section-2.1.1)
for guidance on subject line character limits.
minLength: 1
content:
type: array
description: An array of objects, each containing a message body's
content and [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types).
You must specify at least one MIME type and may include multiple.
To include more than one MIME type, add an object for each type
to the array.
items:
type: object
properties:
type:
type: string
description: The MIME type of the content assigned in the `value`
property of this object (e.g., `text/plain` or `text/html`).
minLength: 1
value:
type: string
description: The content of your message in the specified MIME
type assigned in the `type` property of this object.
minLength: 1
required:
- type
- value
attachments:
type: array
description: An array of objects where you can define any attachments
to be included with the message. Each object contains a `content`
property, which must be a Base64 encoded string of the attachment
itself, and `type`, `filename`, `disposition`, and `content_id`
properties that tell SendGrid how to handle the attachment.
items:
type: object
properties:
content:
type: string
description: The Base64 encoded content of the attachment.
minLength: 1
type:
type: string
description: The MIME type of the content you are attaching
(e.g., `image/jpeg` or `application/pdf`).
minLength: 1
filename:
type: string
description: The attachment's filename, including the file extension.
disposition:
type: string
default: attachment
description: The attachment's content-disposition specifies
how you would like the attachment to be displayed. For example,
`inline` results in the attached file being displayed automatically
within the message while `attachment` results in the attached
file requiring some action to be taken before it is displayed
such as opening or downloading the file.
$ref: '#/components/schemas/Disposition'
content_id:
type: string
description: The attachment's content ID. The `content_id` is
used when the `disposition` is set to `inline` and the attachment
is an image, allowing the file to be displayed within the
body of the email.
required:
- content
- filename
template_id:
type: string
description: "An email template ID. A template that contains a subject\
\ and content\u2014either text or html\u2014will override any subject\
\ and content values specified at the `personalizations` or message\
\ level. If a template ID begins with `d-`, it is a dynamic template\
\ and will work with the `dynamic_template_data` property. If the\
\ template ID does not begin with `d-`, it is a standard SendGrid\
\ template and will work with the `substitutions` property. See\
\ [**How to Send an Email with Dynamic Templates**](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates)\
\ for more information about working with templates."
headers:
description: 'A collection of JSON property name and property value
pairs allowing you to specify handling instructions for your email.
You may not override the following headers: `x-sg-id`, `x-sg-eid`,
`received`, `dkim-signature`, `Content-Type`, `Content-Transfer-Encoding`,
`To`, `From`, `Subject`, `Reply-To`, `CC`, `BCC`.'
type: object
categories:
type: array
description: An array of category names assigned to this message.
Categories allow you to group messages by categories you define.
Categories should be used sparingly to create general groups that
are relevant to you. Categories are not meant to be used to track
individual mail sends. For more granular categorization and tracking,
use the `custom_args` property. A category name cannot exceed 255
characters. See [**Working with Categories**](https://docs.sendgrid.com/for-developers/sending-email/categories)
for more information.
uniqueItems: true
maxItems: 10
items:
type: string
maxLength: 255
custom_args:
type: string
description: Values that are specific to the entire send that will
be carried along with the email and its activity data. Substitutions
will not be made on custom arguments, so any string that is assigned
to this property will be assumed to be the custom argument that
you would like to be used. This parameter is overridden by `custom_args`
set at the personalizations level. Total `custom_args` size may
not exceed 10,000 bytes.
send_at:
type: integer
description: A [unix timestamp](https://en.wikipedia.org/wiki/Unix_time)
allowing you to specify when your email should be sent. A send cannot
be scheduled more than 72 hours in advance. This property may be
overridden by the `send_at` property set at the personalizations
level.
batch_id:
type: string
description: An ID representing a batch of emails to be sent at the
same time. Including a `batch_id` in your request allows you to
include this email in that batch. It also enables you to cancel
or pause the delivery of that batch. See the [Scheduled Sends API](https://sendgrid.com/docs/api-reference/)
for more information about scheduling your email.
asm:
type: object
description: An object allowing you to specify how to handle unsubscribes.
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. See [**Suppression
Groups**](https://www.twilio.com/docs/sendgrid/api-reference/suppressions-unsubscribe-groups/create-a-new-suppression-group)
for more information.
properties:
group_id:
type: integer
description: The unsubscribe group to associate with this email.
See the [Suppressions API](https://docs.sendgrid.com/api-reference/suppressions/)
to manage unsubscribe group IDs.
groups_to_display:
type: array
description: An array containing the unsubscribe groups that you
would like to be displayed to a recipient on the unsubscribe
preferences page. This page is displayed in the recipient's
browser when they click the unsubscribe link in your message.
maxItems: 25
items:
type: integer
required:
- group_id
ip_pool_name:
type: string
description: The IP Pool that you would like to send this email from.
IP Pools allow you to group your dedicated Twilio SendGrid IP addresses
in order to have more control over your deliverability. See [**IP
Pools**](https://docs.sendgrid.com/ui/account-and-settings/ip-pools)
for more information.
minLength: 2
maxLength: 64
mail_settings:
type: object
description: A collection of different mail settings that you can
use to specify how you would like this email to be handled. Mail
settings provide extra functionality to your mail send. See [**Mail
Settings**](https://docs.sendgrid.com/ui/account-and-settings/mail)
for more information.
properties:
bypass_list_management:
type: object
description: Allows you to bypass all unsubscribe groups and suppressions
to ensure that the email is delivered to every single recipient.
This should only be used in emergencies when it is absolutely
necessary that every recipient receives your email. This filter
cannot be combined with any other bypass filters. See the [the
"Bypass suppressions" section of our **Suppressions Overview**](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions)
for more about bypass filters.
properties:
enable:
type: boolean
description: Indicates if this setting is enabled.
bypass_spam_management:
type: object
description: Allows you to bypass the spam report list to ensure
that the email is delivered to recipients. Bounce and unsubscribe
lists will still be checked; addresses on these other lists
will not receive the message. This filter cannot be combined
with the `bypass_list_management` filter. See the [the "Bypass
suppressions" section of our **Suppressions Overview**](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions)
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_mail_v3.yaml