Skip to contentSkip to navigationSkip to topbar
On this page

v2 Mail Send


(warning)

This documentation is for the SendGrid Web API v2

We will deprecate this version on February 10, 2025. To access all the latest features and upcoming developments, please see our v3 API. For assistance with transitioning, refer to our migration guide.

This endpoint allows you to send email over SendGrid's Web API v2. For information about the latest mail send endpoint, please visit our Web API v3 Mail Send documentation. We encourage our current v2 API customers to migrate to the new endpoint, so they can take advantage of our latest features.

There are a number of official SendGrid libraries that will help you send email through the Web API v2. We recommend using these if possible. Check our API Libraries page to view a list of supported libraries.


Parameters

parameters page anchor
URI ParameterRequiredRequirementsDescription
toYesMust be a valid email addressSpecify a recipient email as a single email with this parameter. To send to multiple emails, use an array to specify each email, for example: to[]=a@mail.com&to[]=b@mail.com. You can also use the To parameter in the x-smtpapi header to add additional recipients. If you use the API to parameter to specify a single recipient, that recipient is visible in the For field of the received header—so if you specify a single address, it should be an address that you are comfortable with your customer seeing. For example, use a generic email address in the to field that your customer is already going to see, like your from address. To completely omit the email showing up in the from header: either specify multiple addresses in the to field as an array, for example, to[]=a@mail.com&to[]=b@mail.com, or use the V3 mail send endpoint.
tonameNoMust be a string. If the to parameter is an array, toname must be an array with the exact number of array elements as the to fieldGive a name to the recipient. This can also be passed as an array if the to parameter above is an array. Example: toname[]=Alpha[]=Beta.
x-smtpapiNoMust be in valid JSON formatPlease review the SMTP API to view documentation on what you can do with the JSON headers
subjectYesMust be a valid stringThe subject of your email
textNoAPI call must include at least one of the text or html parameters.The plain text content of your email message.
htmlNoAPI call must include at least one of the text or html parameters.The HTML content of your email message.
fromYesMust be a valid email address from your domainThis is where the email will appear to originate from for your recipient
ccNoMust be a valid email addressThis can also be passed in as an array of email addresses for multiple recipients. Example: cc[]=a@mail.com&cc[]=b@mail.com.
ccnameNoMust be a valid email addressThis is the name be appended to the cc field.
bccNoMust be a valid email addressThis can also be passed in as an array of email addresses for multiple recipients. Example: bcc[]=a@mail.com&bcc[]=b@mail.com.
bccnameNoMust be a valid email addressThis is the name appended to the bcc field.
fromnameNoMust a valid stringThis is the name appended to the from email field (i.e. your name or company name)
replytoNoMust be a valid email addressAppend a reply-to field to your email message
dateNoMust be a valid dateSpecify the date header of your email. One example: "Thu, 21 Dec 2000 16:01:07 +0200". PHP developers can use: date('r');
filesNoMust be less than 7MBFiles to be attached. The file contents must be part of the multipart HTTP POST. Ex: files[file1.jpg]=file1.jpg&files[file2.pdf]=file2.pdf
contentNoRequired for sending inline imagesContent IDs of the files to be used as inline images. Content IDs should match the cids used in the HTML markup. Ex: content[file1.jpg]=ii_139db99fdb5c3704 would correspond with the HTML <img src="cid:ii_139db99fdb5c3704"></img> and files[file1.jpg] would contain the contents.
headersNoMust be in valid JSON format without integersA collection of key/value pairs in JSON format. This is specifically for non-SendGrid custom extension headers(link takes you to an external page). Each key represents a header name and the value the header value. Ex: {"X-Accept-Language": "en", "X-Mailer": "MyApp"}

(information)

Info

SendGrid's API keys should be used when sending email over the API. API keys are preferred because you can revoke an API key at any time without changing your username and password. You can also limit the permissions of an API key, which reduces the potential for harm in the event that your API key is compromised.

When using an API key, pass it in an Authorization header and omit the api_user and api_key parameters from your request. Pass the API key as a Bearer Token: "Authorization: Bearer <Your API Key>"

For more information, see Upgrading your authentication method to API Keys.

Send to a single recipient

send-to-a-single-recipient page anchor
JSONXML

Call

POSThttps://api.sendgrid.com/api/mail.send.json
POST Datato=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
{
2
"message": "success"
3
}
(information)

Info

You can have up to 10,000 recipients per Web API v2 request. While we do not enforce rate limits on sending mail via the v2 Mail Send endpoint, we do recommend that users avoid making more than 3,000 API requests per second.

Send to multiple recipients

send-to-multiple-recipients page anchor
JSONXML
POSThttps://api.sendgrid.com/api/mail.send.json
POST Datato[]=destination@example.com&to[]=destination2@example.com&toname[]=Destination&to[]=example@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com
1
{
2
"message": "success"
3
}

Sending with a CC and CCname

sending-with-a-cc-and-ccname page anchor
JSONXML
POSThttps://api.sendgrid.com/api/mail.send.json
POST Datato[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com
1
{
2
"message": "success"
3
}

Sending with a BCC and BCCname

sending-with-a-bcc-and-bccname page anchor
JSONXML
POSThttps://api.sendgrid.com/api/mail.send.json
POST Datato[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com
1
{
2
"message": "success"
3
}

Send to one email recipient

send-to-one-email-recipient page anchor
1
curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
2
-H 'Content-Type: application/x-www-form-urlencoded' \
3
-H 'Authorization: Bearer YOUR_API_KEY' \
4
--data-urlencode "to=destination@example.com" \
5
--data-urlencode "toname=Destination" \
6
--data-urlencode "subject=Example Subject" \
7
--data-urlencode "text=testingtextbody" \
8
--data-urlencode "from=info@domain.com"

Send to multiple email recipients

send-to-multiple-email-recipients page anchor
1
curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
2
-H 'Content-Type: application/x-www-form-urlencoded' \
3
-H 'Authorization: Bearer YOUR_API_KEY' \
4
--data-urlencode "to[]=destination@example.com,example@example.com" \
5
--data-urlencode "toname[]=Destination,Destination2" \
6
--data-urlencode "subject=Example Subject" \
7
--data-urlencode "text=testingtextbody" \
8
--data-urlencode "from=info@domain.com"
(information)

Info

To ensure that an attachment uploads from a local file, use \<@filename>.

1
curl https://api.sendgrid.com/api/mail.send.json \
2
-H 'Authorization: Bearer YOUR_API_KEY' \
3
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
4
-F text="testing text body" --form-string html="<strong>testing html body</strong>" \
5
-F from=test@yourdomain.com -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password \
6
-F files[attachment.pdf\]=@attachment.pdf;type=application/pdf

Send a test with an attachment

send-a-test-with-an-attachment page anchor
1
curl https://api.sendgrid.com/api/mail.send.json \
2
-H 'Authorization: Bearer YOUR_API_KEY' \
3
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
4
-F text="testing text body" --form-string html="<strong>testing html body</strong>" \
5
-F from=test@yourdomain.com \
6
-F files[attachment.gz\]=@f.php.gz

Send a test specifying the file content type by appending ';type=' to the file name

send-a-test-specifying-the-file-content-type-by-appending-type-to-the-file-name page anchor
1
curl https://api.sendgrid.com/api/mail.send.json \
2
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
3
-F text="testing text body" --form-string html="<strong>testing html body</strong>" \
4
-F from=test@yourdomain.com -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password \
5
-F files[attachment.pdf\]=@attachment.pdf;type=application/pdf

The following is a dump of the HTTP data sent to our server to generate an email via our Web API v2.

POST /api/mail.send.json HTTP/1.1
1
Host: sendgrid.com
2
Accept: */*
3
Content-Length: 999
4
Expect: 100-continue
5
Content-Type: multipart/form-data; boundary=----------------------------400f182a9360
6
Authorization: Bearer YOUR_API_KEY
7
HTTP/1.1 100 Continue
8
------------------------------400f182a9360
9
Content-Disposition: form-data; name="to"
10
someone@somewhere.com
11
------------------------------400f182a9360
12
Content-Disposition: form-data; name="subject"
13
test of file sends
14
------------------------------400f182a9360
15
Content-Disposition: form-data; name="html"
16
the HTML
17
------------------------------400f182a9360
18
Content-Disposition: form-data; name="text"
19
the plain text
20
------------------------------400f182a9360
21
Content-Disposition: form-data; name="from"
22
example@sendgrid.com
23
------------------------------400f182a9360
24
Content-Disposition: form-data; name="files[myfile]"; filename="myfile"
25
Content-Type: application/octet-stream
26
file with stuff in it
27
------------------------------400f182a9360--
28
HTTP/1.1 200 OK
29
Server: nginx/0.7.65
30
Date: Fri, 03 Jun 2011 22:30:58 GMT
31
Content-Type: application/json
32
Transfer-Encoding: chunked
33
Connection: keep-alive
{"message":"success"}