Skip to contentSkip to navigationSkip to topbar
On this page

Mail Send


(information)

Info

Regional Email sending in the European Union (EU) is GA for Twilio SendGrid Pro plan or above(link takes you to an external page). Learn More(link takes you to an external page)


Operation overview

operation-overview page anchor

POST/v3/mail/send

Base url: https://api.sendgrid.com (for global users and subusers)

Base url: https://api.eu.sendgrid.com (for EU regional subusers)

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

The overview page also includes links to SendGrid's Email API quickstarts and helper libraries to get you working with this endpoint even faster.


Authentication

authentication page anchor
Property nameTypeRequiredDescription
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>

Content-Encodingenum<string>Optional

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(link takes you to an external page) to have gzip enabled on your account.

Possible values:
gzip
Encoding type:application/json
SchemaExample
Property nameTypeRequiredDescriptionChild properties
personalizationsarray[object]required

An array of messages and their metadata. Each object within the personalizations array can be thought of as a mail envelope—it defines who should receive an individual message and how that message should be handled. See Personalizations for more information.


fromobjectrequired

reply_toobjectOptional

reply_to_listarray[object]Optional

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.


subjectstringOptional

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(link takes you to an external page) for guidance on subject line character limits.

Min length: 1

contentarray[object]Optional

An array of objects, each containing a message body's content and MIME type(link takes you to an external page). 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.


attachmentsarray[object]Optional

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.


template_idstringOptional

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. 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 for more information about working with templates.


headersobjectOptional

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.


categoriesarray[string]Optional

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 for more information.


custom_argsstringOptional

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_atintegerOptional

A unix timestamp(link takes you to an external page) 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_idstringOptional

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 for more information about scheduling your email.


asmobjectOptional

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 for more information.


ip_pool_namestringOptional

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 for more information.

Min length: 2Max length: 64

mail_settingsobjectOptional

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 for more information.


tracking_settingsobjectOptional

Settings to determine how you would like to track the metrics of how your recipients interact with your email. See Tracking Settings for more information.

202400401403404405413500

Accepted

v3 Mail SendLink to code sample: v3 Mail Send
1
const client = require("@sendgrid/mail");
2
3
client.setApiKey(process.env.SENDGRID_API_KEY);
4
5
const message = {
6
personalizations: [
7
{
8
to: [
9
{
10
email: "alex@example.com",
11
name: "Alex",
12
},
13
{
14
email: "bola@example.com",
15
name: "Bola",
16
},
17
],
18
cc: [
19
{
20
email: "charlie@example.com",
21
name: "Charlie",
22
},
23
],
24
bcc: [
25
{
26
email: "dana@example.com",
27
name: "Dana",
28
},
29
],
30
},
31
{
32
from: {
33
email: "sales@example.com",
34
name: "Example Sales Team",
35
},
36
to: [
37
{
38
email: "ira@example.com",
39
name: "Ira",
40
},
41
],
42
bcc: [
43
{
44
email: "lee@example.com",
45
name: "Lee",
46
},
47
],
48
},
49
],
50
from: {
51
email: "orders@example.com",
52
name: "Example Order Confirmation",
53
},
54
replyTo: {
55
email: "customer_service@example.com",
56
name: "Example Customer Service Team",
57
},
58
subject: "Your Example Order Confirmation",
59
content: [
60
{
61
type: "text/html",
62
value:
63
"<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>",
64
},
65
],
66
attachments: [
67
{
68
content:
69
"PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
70
filename: "index.html",
71
type: "text/html",
72
disposition: "attachment",
73
},
74
],
75
categories: ["cake", "pie", "baking"],
76
sendAt: 1617260400,
77
batchId: "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",
78
asm: {
79
groupId: 12345,
80
groupsToDisplay: [12345],
81
},
82
ipPoolName: "transactional email",
83
mailSettings: {
84
bypassListManagement: {
85
enable: false,
86
},
87
footer: {
88
enable: false,
89
},
90
sandboxMode: {
91
enable: false,
92
},
93
},
94
trackingSettings: {
95
clickTracking: {
96
enable: true,
97
enableText: false,
98
},
99
openTracking: {
100
enable: true,
101
substitutionTag: "%open-track%",
102
},
103
subscriptionTracking: {
104
enable: false,
105
},
106
},
107
};
108
109
client
110
.send(message)
111
.then(() => console.log("Mail sent successfully"))
112
.catch((error) => {
113
console.error(error);
114
});

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.