Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

Rate this page:

v2 Mail Send

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

URI Parameter Required Requirements Description
to Yes Must be a valid email address Specify 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.
toname No Must 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 field Give 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-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 (i.e. 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> and files[file1.jpg] would contain the contents.
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"}

Sending email

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. You can pass the API Key as a Bearer Token: "Authorization: Bearer <Your API Key>"

Send to a single recipient

Call

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

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

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

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

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data to[]=destination@example.com&to[]=destination2@example.com&toname[]=Destination&to[]=example@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to[]=destination@example.com&to[]=destination2@example.com&toname[]=Destination&to[]=example@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

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

Sending with a CC and CCname

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data to[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

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

Sending with a BCC and BCCname

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data to[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

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

cURL Examples

Send to one email recipient

curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode "to=destination@example.com" \
     --data-urlencode "toname=Destination" \
     --data-urlencode "subject=Example Subject" \
     --data-urlencode "text=testingtextbody" \
     --data-urlencode "from=info@domain.com"

Send to multiple email recipients

curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode "to[]=destination@example.com,example@example.com" \
     --data-urlencode "toname[]=Destination,Destination2" \
     --data-urlencode "subject=Example Subject" \
     --data-urlencode "text=testingtextbody" \
     --data-urlencode "from=info@domain.com"

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

curl https://api.sendgrid.com/api/mail.send.json \
-H 'Authorization: Bearer YOUR_API_KEY' \
-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

Send a test with an attachment

curl https://api.sendgrid.com/api/mail.send.json \
-H 'Authorization: Bearer YOUR_API_KEY' \
-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 files\[attachment.gz\]=@f.php.gz

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

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 v2.

POST /api/mail.send.json HTTP/1.1
Host: sendgrid.com
Accept: */*
Content-Length: 999
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------400f182a9360
Authorization: Bearer YOUR_API_KEY
HTTP/1.1 100 Continue
------------------------------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
{"message":"success"}
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more