Menu

Mail Send

POST /mail/send

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. Talk to your CSM if you are interested in this functionality. 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:

  1. Add a Content-Encoding header, with a value of gzip.
    a. Content-Encoding: gzip
  2. Send the gzip as a data-binary.
    a. --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 and/or bounce messages from the recipient of the email.

Usage Considerations

  • reply_to is mutually exclusive with reply_to_list. If both are used, then the API call will be rejected.
  • The reply_to_list object, when used, must at least have an email parameter and may also contain a name parameter.
  • Each email address in the reply_to_list should be unique.
  • There is a limit of 1000 reply_to_list emails per mail/send request.
  • In SMTP calls, we will omit any invalid emails.

Possible 400 Error Messages

  • reply_to is mutually exclusive with reply_to_list.
  • The reply_to_list object, when used, must at least have an email parameter and may also contain a name parameter.
  • Each email address in the reply_to_list should be unique.
  • There is a limit of X reply_to emails per mail/send request.
  • The reply_to_list email does not contain a valid address.
  • The reply_to_list email exceeds the maximum total length of X characters.
  • The reply_to_list email parameter is required.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Request Body

object
personalizations
array[object]

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: 1000
required
from
object
email
string

The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.

format: email
required
name
string

A name or title associated with the sending email address.

to
array[object]
email
string

The intended recipient's email address.

format: email
name
string

The intended recipient's name.

cc
array[object]

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: 1000
email
string

The intended recipient's email address.

format: email
name
string

The intended recipient's name.

bcc
array[object]

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: 1000
email
string

The intended recipient's email address.

format: email
name
string

The intended recipient's name.

subject
string

The subject of your email. See character length requirements according to RFC 2822.

minLength: 1
headers
object

A 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
object

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
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".

custom_args
object

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.

send_at
integer

A unix timestamp allowing you to specify when your email should be delivered. Scheduling delivery more than 72 hours in advance is forbidden.

from
object
required
email
string

The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.

format: email
required
name
string

A name or title associated with the sending email address.

reply_to
object
email
string

The email address where any replies or bounces will be returned.

format: email
required
name
string

A name or title associated with the reply_to email address.

reply_to_list
array[object]

An array of recipients who will receive replies and/or bounces. 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: True
email
string

The email address where any replies or bounces will be returned.

format: email
name
string

A name or title associated with the reply_to_list email address.

subject
string

The global or 'message level' subject of your email. This may be overridden by subject lines set in personalizations.

minLength: 1
required
content
array[object]

An 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.

required
type
string

The MIME type of the content you are including in your email (e.g., “text/plain” or “text/html”).

minLength: 1
value
string

The actual content of the specified MIME type that you are including in your email.

minLength: 1
attachments
array[object]

An array of objects where you can specify any attachments you want to include.

content
string

The Base64 encoded content of the attachment.

minLength: 1
type
string

The MIME type of the content you are attaching (e.g., “text/plain” or “text/html”).

minLength: 1
filename
string

The attachment's filename.

disposition
string

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.

default: attachmentAllowed Values: inline, attachment
content_id
string

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.

template_id
string

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.

headers
object

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.

categories
array[string]

An array of category names for this message. Each category name may not exceed 255 characters.

maxItems: 10uniqueItems: True
custom_args
string

Values 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.

send_at
integer

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.

batch_id
string

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.

asm
object

An object allowing you to specify how to handle unsubscribes.

group_id
integer

The unsubscribe group to associate with this email.

required
groups_to_display
array[integer]

An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.

maxItems: 25
ip_pool_name
string

The IP Pool that you would like to send this email from.

maxLength: 64minLength: 2
mail_settings
object

A collection of different mail settings that you can use to specify how you would like this email to be handled.

bypass_list_management
object

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.

enable
boolean

Indicates if this setting is enabled.

bypass_spam_management
object

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.

enable
boolean

Indicates if this setting is enabled.

bypass_bounce_management
object

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.

enable
boolean

Indicates if this setting is enabled.

bypass_unsubscribe_management
object

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.

enable
boolean

Indicates if this setting is enabled.

footer
object

The default footer that you would like included on every email.

enable
boolean

Indicates if this setting is enabled.

text
string

The plain text content of your footer.

html
string

The HTML content of your footer.

sandbox_mode
object

Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.

enable
boolean

Indicates if this setting is enabled.

tracking_settings
object

Settings to determine how you would like to track the metrics of how your recipients interact with your email.

click_tracking
object

Allows you to track if a recipient clicked a link in your email.

enable
boolean

Indicates if this setting is enabled.

enable_text
boolean

Indicates if this setting should be included in the text/plain portion of your email.

open_tracking
object

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.

enable
boolean

Indicates if this setting is enabled.

substitution_tag
string

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.

subscription_tracking
object

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.

enable
boolean

Indicates if this setting is enabled.

text
string

Text to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>

html
string

HTML to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>

substitution_tag
string

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.

ganalytics
object

Allows you to enable tracking provided by Google Analytics.

enable
boolean

Indicates if this setting is enabled.

utm_source
string

Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)

utm_medium
string

Name of the marketing medium. (e.g. Email)

utm_term
string

Used to identify any paid keywords.

utm_content
string

Used to differentiate your campaign from advertisements.

utm_campaign
string

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

No response body.
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more