This 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, please see our v2 API Reference.

SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages: C#, Go, Java, NodeJS, PHP, Python, and Ruby.

Request

1
POST https://api.sendgrid.com/v3/mail/send HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "personalizations": [
    {
      "to": [
        {
          "email": "john@example.com"
        }
      ],
      "subject": "Hello, World!"
    }
  ],
  "from": {
    "email": "from_address@example.com"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "Hello, World!"
    }
  ]
}

Response

1
2
3
{
  HTTP/1.1 202
}
For general information about how to use SendGrid’s Web API v3, please visit our API Overview. You may send mail via the v3 Mail Send endpoint via one of two ways:

Authentication

1
curl -X "POST" "https://api.sendgrid.com/v3/mail/send" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "[YOUR DATA HERE]"
You must authenticate every API request to send mail by including an Authorization header. This header should include the authorization type of Bearer, followed by your API Key that has already been assigned the necessary permissions. Click here for more information.

Limitations

  • The total size of your email, including attachments, must be less than 30MB.
  • The total number of recipients must be less than 1000. This includes all recipients defined within the to, cc, and bcc parameters, across each object that you include in the personalizations array.
  • 3000 requests/sec is the maximum rate at which you may call v3 Mail endpoint.
  • The total length of custom arguments must be less than 10000 bytes.
  • Unicode encoding is not supported for the from field within the personalizations array.
  • The to.name, cc.name, and bcc.name personalizations cannot include either the ; or , characters.
For more specific, parameter level requirements and limitations, see the Request Body Parameters documentation.

Validation

Whenever you make a request to the v3 Mail Send endpoint, your JSON payload is validated before your email is sent. If there are any errors, SendGrid will attempt to identify and return as many issues as possible for each request. For more information, please read our error documentation.

Request Body Parameters

Every request made to /v3/mail/send will require a request body formatted in JSON containing your email’s content and metadata. This may include information such as the recipient’s email address, the return address, and the subject.
JSON Parameter Type Required Limitations Details
personalizations array of objects Yes Min 1, Max 1000
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. For more information, please see our documentation on Personalizations. Parameters in personalizations will override the parameters of the same name from the message level.
to array of email objects Yes Min 1
An array of recipients. Each email object within this array may contain the recipient’s name, but must always contain the recipient’s email.
email string Yes
The email address of the recipient.
name string No
The name of the recipient. May not contain ; or ,
cc array of email objects No
An array of recipients who will receive a copy of your email. Each email object within this array may contain the recipient’s name, but must always contain the recipient’s email.
email string Yes
The email address of the recipient.
name string No
The name of the recipient. May not contain ; or ,
bcc array of email objects No
An array of recipients who will receive a blind carbon copy of your email. Each email object within this array may contain the recipient’s name, but must always contain the recipient’s email.
email string Yes
The email address of the recipient.
name string No
The name of the recipient. May not contain ; or ,
subject string No
The subject line of your email.
headers object No
An object allowing you to specify specific handling instructions for your email.
substitutions object No Max 100 substitutions, or 10K bytes, per personalization object.
An object following the pattern "substitution_tag":"value to substitute". All are assumed to be strings. These substitutions will apply to the content of your email, in addition to the subject and reply-to parameters.

You may not include more than 100 substitutions per personalization object, and the total collective size of your substitutions may not exceed 10,000 bytes per personalization object.
custom_args object No May not exceed 10,000 bytes
These are values that are specific to this personalization that will be carried along with the email, activity data, and links. Substitutions will not be made on custom arguments. personalizations[x].custom_args will be merged with message level custom_args, overriding any conflicting keys. The combined total size of the resulting custom arguments, after merging, for each personalization may not exceed 10,000 bytes.
send_at integer No Value in seconds (not ms)
A unix timestamp allowing you to specify when you want your email to be sent from SendGrid. 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 those times (for example, scheduling at 10:53) can result in lower deferral rates because it won’t be going through our servers at the same times as everyone else’s mail.
from object Yes May not include Unicode encoding.
An email object containing the email address and name of the sender. Unicode encoding is not supported for the from field.
email string Yes
The email address of the sender.
name string No
The name of the sender.
reply_to object No
An email object containing the email address and name of the individual who should receive responses to your email.
email string Yes
The email address to which responses will be sent.
name string No
The name of the individual who will receive responses to the email.
subject string Yes
The subject of your email. This may be overridden by personalizations[x].subject.
content array of objects Yes* Min 1*
An array in which you may specify the content of your email. You can include multiple mime types of content, but you must specify at least one. To include more than one mime type, simply add another object to the array containing the type and value parameters. If included, text/plain and text/html must be the first indices of the array in this order. If you choose to include the text/plain or text/html mime types, they must be the first indices of the content array in the order text/plain, text/html.*Content is NOT mandatory if you using a transactional template and have defined the template_id in the Request
type string Yes Min 1
The mime type of the content you are including in your email. For example, text/plain or text/html.
value string Yes Min 1
The actual content of the specified mime type that you are including in your email.
attachments array of objects No
An array of objects in which you can specify any attachments you want to include.
content string Yes
The Base64 encoded content of the attachment.
type string No
The mime type of the content you are attaching. For example, application/pdf or image/jpeg.
filename string Yes
The filename of the attachment.
disposition string No
The content-disposition of the attachment specifying 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 (e.g. opening or downloading the file). Defaults to "attachment". Can be either "attachment" or "inline".
content_id string No
A unique id that you specify for the attachment. 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. Ex: <img src="cid:ii_139db99fdb5c3704"></img>
template_id string No
The id of a template that you would like to use. If you use a template that contains content and a subject (either text or html), you do not need to specify those in the respective personalizations or message level parameters.
sections custom object No
An object of key/value pairs that define large blocks of content that can be inserted into your emails using substitution tags.
headers custom object No
An object containing key/value pairs of header names and the value to substitute for them. You must ensure these are properly encoded if they contain unicode characters. Must not be any of the following reserved headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC
categories array of strings No Max 255
An array of category names for this message. Each category name may not exceed 255 characters. You cannot have more than 10 categories per request.
custom_args custom object No
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 entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by any conflicting personalizations[x].custom_args if that parameter has been defined. If personalizations[x].custom_args has been defined but does not conflict with the values defined within this parameter, the two will be merged. The combined total size of these custom arguments may not exceed 10,000 bytes.
send_at integer No
A unix timestamp allowing you to specify when you want your email to be sent from SendGrid. This is not necessary if you want the email to be sent at the time of your API request.
batch_id string No
This ID represents a batch of emails (AKA multiple sends of the same email) to be associated to each other for scheduling. Including a batch_id in your request allows you to include this email in that batch, and also enables you to cancel or pause the delivery of that entire batch. For more information, please read about Cancel Scheduled Sends.
asm object No
An object allowing you to specify how to handle unsubscribes.
group_id integer Yes
The unsubscribe group to associate with this email.
groups_to_display array of integers No Max 25
An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.
ip_pool_name string No Min 2, Max 64
The IP Pool that you would like to send this email from.
mail_settings object No
A collection of different mail settings that you can use to specify how you would like this email to be handled.
bcc object No
The address specified in the mail_settings.bcc object will receive a blind carbon copy (BCC) of the very first personalization defined in the personalizations array.
enable boolean No true or false
Indicates if this setting is enabled.
email string No
The email address that you would like to receive the BCC.
bypass_list_management object No
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. Ex: outage emails, or forgot password emails.
enable boolean No true or false
Indicates if this setting is enabled.
footer object No
The default footer that you would like appended to the bottom of every email.
enable boolean No true or false
Indicates if this setting is enabled.
text string No
The plain text content of your footer.
html string No
The HTML content of your footer.
sandbox_mode object No
This allows you to send a test email to ensure that your request body is valid and formatted correctly. For more information, please see our Classroom.
enable boolean No true or false
Indicates if this setting is enabled.
spam_check object No
This allows you to test the content of your email for spam.
enable boolean No true or false
Indicates if this setting is enabled.
threshold integer No Max 10
The threshold used to determine if your content qualifies as spam on a scale from 1 to 10, with 10 being most strict, or most likely to be considered as spam.
post_to_url string No
An Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to. The post_to_url parameter must start with http:// or https://.
tracking_settings object No
Settings to determine how you would like to track the metrics of how your recipients interact with your email.
click_tracking object No
Allows you to track whether a recipient clicked a link in your email.
enable boolean No true or false
Indicates if this setting is enabled.
enable_text boolean No true or false
Indicates if this setting should be included in the text/plain portion of your email.
open_tracking object No
Allows you to track whether the email was opened or not, by including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened.
enable boolean No true or false
Indicates if this setting is enabled.
substitution_tag string No
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 No
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 No true or false
Indicates if this setting is enabled.
text string No
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 No
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 No
A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the textand html parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting.
ganalytics object No
Allows you to enable tracking provided by Google Analytics.
enable boolean No true or false
Indicates if this setting is enabled.
utm_source string No
Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)
utm_medium string No
Name of the marketing medium. (e.g. Email)
utm_term string No
Used to identify any paid keywords.
utm_content string No
Used to differentiate your campaign from advertisements.
utm_campaign string No
The name of the campaign.

Response Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Response Code: 202 Accepted
Response Headers:
    Access-Control-Allow-Headers →Authorization, Content-Type, On-behalf-of, x-sg-elas-acl
    Access-Control-Allow-Methods →POST
    Access-Control-Allow-Origin →https://sendgrid.api-docs.io
    Access-Control-Max-Age →600
    Connection →keep-alive
    Content-Length →0
    Content-Type →text/plain; charset=utf-8
    Date →Mon, 23 Oct 2017 23:09:41 GMT
    Server →nginx
    X-Message-Id →kA5kcHA8SVGtVh5S9rAUew
    X-No-CORS-Reason →https://sendgrid.com/docs/Classroom/Basics/API/cors.html
Response Body:

If you are using the Event Webhook, it’s best practice to store your X-Message-ID data help with deduplications in your webhook data.