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 »

send

Send email.

This is not a sandbox. These are real messages that consume credits on your account.

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[]=a@mail.com[]=b@mail.com. 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[]=a@mail.com&cc[]=b@mail.com.
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[]=a@mail.com&bcc[]=b@mail.com.
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 RFC 2822 formatted 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=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

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=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

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[]=destination@example.com&toname[]=Destination&to[]=destination2@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com

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[]=destination@example.com&toname[]=Destination&to[]=destination2@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com

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[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

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[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

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[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

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[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
<result>
   <message>success</message>
</result>

cURL Examples

Send to one email recipient

1
curl -d 'to=destination@example.com&amp;toname=Destination&amp;subject=Example Subject&amp;text=testingtextbody&amp;from=info@domain.com&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[]=destination@example.com&amp;toname[]=Destination&amp;to[]=destination2@example.com&amp;toname[]=Destination2&amp;subject=Example Subject&amp;text=testingtextbody&amp;from=info@domain.com&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=recipient@domain.com -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=recipient@domain.com -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"

someone@somewhere.com

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

example@sendgrid.com

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