Mail Send
POST /v3/mail/send
Base url: https://api.sendgrid.com
The Mail Send endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, see our v2 API Reference.
Helper Libraries
Twilio SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages:
Dynamic Transactional Templates and Handlebars
In order to send a dynamic template, specify the template ID with the template_id parameter.
To specify handlebar substitutions, define your substitutions in the request JSON with this syntax:
"dynamic_template_data": {
"guest": "Jane Doe",
"partysize": "4",
"english": true,
"date": "April 1st, 2021"
}
For more information about Dynamic Transactional Templates and Handlebars, see our documentation and reference pages.
Mail Body Compression
Mail body compression is available to some high volume accounts. Mail body compression works by setting up a JSON payload as defined on this page, then compressing it with gzip (the gzip file can be no more than 30mb).
To use mail body compression, first submit a request to support to have gzip enabled on your account. Once gzip is enabled, follow these steps:
- Add a
Content-Encodingheader, with a value ofgzip:Content-Encoding: gzip - Send the gzip as a data-binary:
--data-binary '@data.json.gz'
Multiple Reply-To Emails
Using reply_to_list allows senders to include more than one recipient email address to receive reply messages from the recipient of the email.
Usage Considerations
reply_tois mutually exclusive withreply_to_list. If both are used, then the API call will be rejected.- The
reply_to_listobject, when used, must at least have an email parameter and may also contain a name parameter. - Each email address in the
reply_to_listshould be unique. - There is a limit of 1000
reply_to_listemails per mail/send request. - In SMTP calls, we will omit any invalid emails.
Possible 400 Error Messages
reply_tois mutually exclusive withreply_to_list.- The
reply_to_listobject, when used, must at least have an email parameter and may also contain a name parameter. - Each email address in the
reply_to_listshould be unique. - There is a limit of X
reply_toemails per mail/send request. - The
reply_to_listemail does not contain a valid address. - The
reply_to_listemail exceeds the maximum total length of X characters. - The
reply_to_listemail parameter is required.
Authentication
- API Key
Headers
Request Body
An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled. See our Personalizations documentation for examples.
maxItems: 1000The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.
format: emailA name or title associated with the sending email address.
The intended recipient's email address.
format: emailThe intended recipient's name.
An array of recipients who will receive a copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.
maxItems: 1000The intended recipient's email address.
format: emailThe intended recipient's name.
An array of recipients who will receive a blind carbon copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.
maxItems: 1000The intended recipient's email address.
format: emailThe intended recipient's name.
The subject of your email. See character length requirements according to RFC 2822.
minLength: 1A collection of JSON key/value pairs allowing you to specify handling instructions for your email. You may not overwrite 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 allow you to insert data without using Dynamic Transactional Templates. This field should not be used in combination with a Dynamic Transactional Template, which can be identified by a template_id starting with d-. This field is a collection of key/value pairs following the pattern "substitution_tag":"value to substitute". The key/value pairs must be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the subject and reply-to parameters. The total collective size of your substitutions may not exceed 10,000 bytes per personalization object.
Dynamic template data is available using Handlebars syntax in Dynamic Transactional Templates. This field should be used in combination with a Dynamic Transactional Template, which can be identified by a template_id starting with d-. This field is a collection of key/value pairs following the pattern "variable_name":"value to insert".
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 entered into this parameter will be assumed to be the custom argument that you would like to be used. This field may not exceed 10,000 bytes.
A unix timestamp allowing you to specify when your email should be delivered. Scheduling delivery more than 72 hours in advance is forbidden.
The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.
format: emailA name or title associated with the sending email address.
The email address where any replies will be sent.
format: emailA name or title associated with the reply_to email address.
An array of recipients who will receive replies. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name. You can either choose to use “reply_to” field or “reply_to_list” but not both.
maxItems: 1000uniqueItems: TrueThe email address where any replies will be returned.
format: emailA name or title associated with the reply_to_list email address.
The global or 'message level' subject of your email. This may be overridden by subject lines set in personalizations.
minLength: 1An array where you can specify the content of your email. You can include multiple MIME types of content, but you must specify at least one MIME type. To include more than one MIME type, add another object to the array containing the type and value parameters.
The MIME type of the content you are including in your email (e.g., “text/plain” or “text/html”).
The actual content of the specified MIME type that you are including in your email.
minLength: 1An array of objects where you can specify any attachments you want to include.
The Base64 encoded content of the attachment.
minLength: 1The MIME type of the content you are attaching (e.g., “text/plain” or “text/html”).
The attachment's filename.
The attachment's content-disposition, specifying how you would like the attachment to be displayed. For example, “inline” results in the attached file are displayed automatically within the message while “attachment” results in the attached file require some action to be taken before it is displayed, such as opening or downloading the file.
The attachment's content ID. This 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 your email.
An email template ID. A template that contains a subject and content — either text or html — will override any subject and content values specified at the personalizations or message level.
An object containing key/value pairs of header names and the value to substitute for them. The key/value pairs must be strings. You must ensure these are properly encoded if they contain unicode characters. These headers cannot be one of the reserved headers.
An array of category names for this message. Each category name may not exceed 255 characters.
maxItems: 10uniqueItems: TrueValues that are specific to the entire send that will be carried along with the email and its activity data. Key/value pairs must be strings. Substitutions will not be made on custom arguments, so any string that is entered into this parameter 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.
A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the send_at parameter set at the personalizations level. Delivery cannot be scheduled more than 72 hours in advance. If you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid peak times — for example, scheduling at 10:53 — can result in lower deferral rates due to the reduced traffic during off-peak times.
An ID representing a batch of emails to be sent at the same time. Including a batch_id in your request allows you include this email in that batch. It also enables you to cancel or pause the delivery of that batch. For more information, see the Cancel Scheduled Sends API.
An object allowing you to specify how to handle unsubscribes.
The unsubscribe group to associate with this email.
An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.
maxItems: 25The IP Pool that you would like to send this email from.
maxLength: 64minLength: 2A collection of different mail settings that you can use to specify how you would like this email to be handled.
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 our documentation for more about bypass filters.
Indicates if this setting is enabled.
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 our documentation for more about bypass filters.
Indicates if this setting is enabled.
Allows you to bypass the bounce list to ensure that the email is delivered to recipients. Spam report 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 our documentation for more about bypass filters.
Indicates if this setting is enabled.
Allows you to bypass the global unsubscribe list to ensure that the email is delivered to recipients. Bounce and spam report lists will still be checked; addresses on these other lists will not receive the message. This filter applies only to global unsubscribes and will not bypass group unsubscribes. This filter cannot be combined with the bypass_list_management filter. See our documentation for more about bypass filters.
Indicates if this setting is enabled.
The default footer that you would like included on every email.
Indicates if this setting is enabled.
The plain text content of your footer.
The HTML content of your footer.
Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.
Indicates if this setting is enabled.
Settings to determine how you would like to track the metrics of how your recipients interact with your email.
Allows you to track if a recipient clicked a link in your email.
Indicates if this setting is enabled.
Indicates if this setting should be included in the text/plain portion of your email.
Allows you to track if the email was opened by including a single pixel image in the body of the content. When the pixel is loaded, Twilio SendGrid can log that the email was opened.
Indicates if this setting is enabled.
Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel.
Allows you to insert a subscription management link at the bottom of the text and HTML bodies of your email. If you would like to specify the location of the link within your email, you may use the substitution_tag.
Indicates if this setting is enabled.
Text to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>
HTML to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>
A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the text and html parameters. The URL of the link will be placed at the substitution tag’s location with no additional formatting.
Allows you to enable tracking provided by Google Analytics.
Indicates if this setting is enabled.
Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)
Name of the marketing medium. (e.g. Email)
Used to identify any paid keywords.
Used to differentiate your campaign from advertisements.
The name of the campaign.
{
"personalizations": [
{
"to": [
{
"email": "john_doe@example.com",
"name": "John Doe"
},
{
"email": "julia_doe@example.com",
"name": "Julia Doe"
}
],
"cc": [
{
"email": "jane_doe@example.com",
"name": "Jane Doe"
}
],
"bcc": [
{
"email": "james_doe@example.com",
"name": "Jim Doe"
}
]
},
{
"from": {
"email": "sales@example.com",
"name": "Example Sales Team"
},
"to": [
{
"email": "janice_doe@example.com",
"name": "Janice Doe"
}
],
"bcc": [
{
"email": "jordan_doe@example.com",
"name": "Jordan Doe"
}
]
}
],
"from": {
"email": "orders@example.com",
"name": "Example Order Confirmation"
},
"reply_to": {
"email": "customer_service@example.com",
"name": "Example Customer Service Team"
},
"subject": "Your Example Order Confirmation",
"content": [
{
"type": "text/html",
"value": "<p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>"
}
],
"attachments": [
{
"content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
"filename": "index.html",
"type": "text/html",
"disposition": "attachment"
}
],
"categories": [
"cake",
"pie",
"baking"
],
"send_at": 1617260400,
"batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",
"asm": {
"group_id": 12345,
"groups_to_display": [
12345
]
},
"ip_pool_name": "transactional email",
"mail_settings": {
"bypass_list_management": {
"enable": false
},
"footer": {
"enable": false
},
"sandbox_mode": {
"enable": false
}
},
"tracking_settings": {
"click_tracking": {
"enable": true,
"enable_text": false
},
"open_tracking": {
"enable": true,
"substitution_tag": "%open-track%"
},
"subscription_tracking": {
"enable": false
}
}
}Responses
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
Gzip will take the JSON payload and compresses it into a gzip file. This means that anything in the JSON payload including the attachments will be compressed. The compressed data must also be less than the 30MB maximum for the email with headers, body and attachments.
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
