View and Edit

Mail

This endpoint allows you to send email.

There are a number of official SendGrid libraries to allow for email sending through the Web API. We recommend using these if possible.

View List »

The “Try It” functionality is not a sandbox. These are real API calls that consume emails on your account.

When you make an API request to send a message, we will accept the request and then process the email, meaning that a successful API request does not mean an email was successfully sent. Please see our Event Webhook if you want to be notified of email send status.

send

SendGrid’s API Keys should be used when sending email over the API.

You can have up to 10,000 recipients per API request.

URI Parameter Required Requirements Description
to Yes Must be a valid email address This can also be passed in as an array, to send to multiple locations. Example: to[][email protected]&to[][email protected]. Note that recipients passed in this parameter will be visible as part of the message. If you wish to hide the recipients, use the TO parameter in the x-smtpapi header.
toname No Must be a string. If to parameter is an array, toname must be an array with the exact number of array elements as the to field Give a name to the recipient. This can also be passed as an array if the to above is an array. Example: toname[]=Alpha[]=Beta.
x-smtpapi No Must be in valid JSON format Please review the SMTP API to view documentation on what you can do with the JSON headers
subject Yes Must be a valid string The subject of your email
text No API call must include at least one of the text or html parameters. The plain text content of your email message.
html No API call must include at least one of the text or html parameters. The HTML content of your email message.
from Yes Must be a valid email address from your domain This is where the email will appear to originate from for your recipient
cc No Must be a valid email address This can also be passed in as an array of email addresses for multiple recipients. Example: cc[][email protected]&cc[][email protected].
ccname No Must be a valid email address This is the name be appended to the cc field.
bcc No Must be a valid email address This can also be passed in as an array of email addresses for multiple recipients. Example: bcc[][email protected]&bcc[][email protected].
bccname No Must be a valid email address This is the name appended to the bcc field.
fromname No Must a valid string This is the name appended to the from email field. IE - Your name or company name
replyto No Must be a valid email address Append a reply-to field to your email message
date No Must be a valid date Specify the date header of your email. One example: “Thu, 21 Dec 2000 16:01:07 +0200”. PHP developers can use: date(r);
files No Must be less than 7MB Files 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
content No Required for sending inline images Content 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>
headers No Must be in valid JSON format without integers A collection of key/value pairs in JSON format. This is specifically for non-SendGrid custom extension headers. Each key represents a header name and the value the header value. Ex: {"X-Accept-Language": "en", "X-Mailer": "MyApp"}
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to=[email protected]&toname=Destination&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to=[email protected]&toname=Destination&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

<result>
   <message>success</message>
</result>

Call: Send to Multiple Recipients

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to[]=[email protected]&toname[]=Destination&to[]=[email protected]&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to[]=[email protected]&toname[]=Destination&to[]=[email protected]&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

<result>
   <message>success</message>
</result>

Call: Sending with a CC and CCname

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to[]=[email protected]&toname[]=Destination&cc=[email protected]&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to[]=[email protected]&toname[]=Destination&cc=[email protected]&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

<result>
   <message>success</message>
</result>

Call: Sending with a BCC and BCCname

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to[]=[email protected]&toname[]=Destination&bcc=[email protected]&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&to[]=[email protected]&toname[]=Destination&bcc=[email protected]&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=[email protected]

Response

1
2
3

<result>
   <message>success</message>
</result>

cURL Examples

Send to one email recipient

1

curl -d '[email protected]&amp;toname=Destination&amp;subject=Example Subject&amp;text=testingtextbody&amp;[email protected]&amp;api_user=your_sendgrid_username&amp;api_key=your_sendgrid_password' https://api.sendgrid.com/api/mail.send.json

Send to multiple email recipients

1

curl -d 'to[][email protected]&amp;toname[]=Destination&amp;to[][email protected]&amp;toname[]=Destination2&amp;subject=Example Subject&amp;text=testingtextbody&amp;[email protected]&amp;api_user=your_sendgrid_username&amp;api_key=your_sendgrid_password' https://api.sendgrid.com/api/mail.send.json

Send a test with attachment

1
2
3
4
5

curl https://api.sendgrid.com/api/mail.send.json \
-F to=[email protected] -F toname=test -F subject="Example Subject" \
-F text="testing text body" --form-string html="<strong>testing html body</strong>" \
-F from=test@yourdomain.com -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password \
-F files\[attachment.gz\]=@f.php.gz

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

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

1
2
3
4
5

curl https://api.sendgrid.com/api/mail.send.json \
-F to=[email protected] -F toname=test -F subject="Example Subject" \
-F text="testing text body" --form-string html="<strong>testing html body</strong>" \
-F from=test@yourdomain.com -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password \
-F files\[attachment.pdf\]=@attachment.pdf;type=application/pdf

Raw HTTP Dump

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

1

POST /api/mail.send.json HTTP/1.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

Host: sendgrid.com

Accept: */*

Content-Length: 999

Expect: 100-continue

Content-Type: multipart/form-data; boundary=----------------------------400f182a9360

HTTP/1.1 100 Continue

------------------------------400f182a9360

Content-Disposition: form-data; name="api_user"

YOURUSERNAME

------------------------------400f182a9360

Content-Disposition: form-data; name="api_key"

YOURKEY

------------------------------400f182a9360

Content-Disposition: form-data; name="to"

[email protected]

------------------------------400f182a9360

Content-Disposition: form-data; name="subject"

test of file sends

------------------------------400f182a9360

Content-Disposition: form-data; name="html"

the HTML

------------------------------400f182a9360

Content-Disposition: form-data; name="text"

the plain text

------------------------------400f182a9360

Content-Disposition: form-data; name="from"

[email protected]

------------------------------400f182a9360

Content-Disposition: form-data; name="files[myfile]"; filename="myfile"

Content-Type: application/octet-stream

file with stuff in it

------------------------------400f182a9360--

HTTP/1.1 200 OK

Server: nginx/0.7.65

Date: Fri, 03 Jun 2011 22:30:58 GMT

Content-Type: application/json

Transfer-Encoding: chunked

Connection: keep-alive

1

{"message":"success"}