Mail

This endpoint allows you to send email.

send

Send email.

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. 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
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 and/or html Yes Must include one or both parameters The actual content of your email message. It can be sent as either plain text or HTML for the user to display
from Yes Must be a valid email address from your domain This is where the email will appear to originate from for your recipient
bcc No Must be a valid email address This can also be passed in as an array of email addresses for multiple recipients
fromname No Must a valid string This is 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]=&files[file2.pdf]=
Example Code (PHP)
content No Required for sending inline images Content IDs of the files to be used as inline images. Content IDs should match the cid’s used in the HTML markup. Ex: content[file1.jpg]=ii_139db99fdb5c3704 would correspond with the HTML <img src="cid:ii_139db99fdb5c3704">
headers No Must be in valid JSON format without integers A collection of key/value pairs in JSON format. Each key represents a header name and the value the header value. Ex: {“X-Accept-Language”: “en”, “X-Mailer”: “MyApp”}

Call: Send to One Recipient

1

https://sendgrid.com/api/mail.send.json?api_user=youremail@domain.com&api_key=secureSecret&to=destination@example.com&toname=Destination&subject=Examplev1_(deprecated)Subject&text=testingtextbody&from=info@domain.com

Call: Send to Multiple Recipients 
1

https://sendgrid.com/api/mail.send.json?api_user=youremail@domain.com&api_key=secureSecret&to[]=destination@example.com&toname[]=Destination&to[]=destination2@example.com&toname[]=Destination2&subject=Examplev1_(deprecated)Subject&text=testingtextbody&from=info@domain.com

Response: Success

1
2
3

{
  "message": "success"
}

Response: Error

1
2
3
4
5
6

{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

Call: Send to One Recipient

1

https://sendgrid.com/api/mail.send.xml?api_user=youremail@domain.com&api_key=secureSecret&to=destination@example.com&toname=Destination&subject=Examplev1_(deprecated)Subject&text=testingtextbody&from=info@domain.com

Call: Send to Multiple Recipients 
1

https://sendgrid.com/api/mail.send.xml?api_user=youremail@domain.com&api_key=secureSecret&to[]=destination@example.com&toname[]=Destination&to[]=destination2@example.com&toname[]=Destination2&subject=Examplev1_(deprecated)Subject&text=testingtextbody&from=info@domain.com

Response: Success

1
2
3
4
5
6
7

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5
6
7
8
9
10

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error</message>
   <errors>
      <error>...</error>
      ...
   </errors>
   @nodes
</result>

cURL Examples

Send to one email recipient

1

$ curl -d 'to=destination@example.com&toname=Destination&subject=Example Subject&text=testingtextbody&from=info@domain.com&api_user=sendgridUsername&api_key=sendgridPassword' https://sendgrid.com/api/mail.send.json

Send to multiple email recipients

1

$ curl -d 'to[]=destination@example.com&toname[]=Destination&to[]=destination2@example.com&toname[]=Destination2&subject=Example Subject&text=testingtextbody&from=info@domain.com&api_user=sendgridUsername&api_key=sendgridPassword' https://sendgrid.com/api/mail.send.json

Send a test with attachment

1
2
3
4
5

$ curl https://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 https://sendgrid.com/api/mail.send.json

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