mail.md

layout

page

weight

0

title

Mail

seo

title	override	description
Mail - Send Email Using HTTP - SendGrid Documentation \| SendGrid	true	The mail send endpoint allows you to send email through SendGrid using a POST request. Find documentation and examples on how to use the endpoint.

navigation

show
true

This endpoint allows you to send email.

{% info %} 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 » {% endinfo %}

{% warning %} The "Try It" functionality is not a sandbox. These are real API calls that consume emails on your account. {% endwarning %}

{% info %} 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. {% endinfo %}

{% anchor h2 %} send {% endanchor %}

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

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

{% parameters mail %} {% parameter '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.' %} {% parameter '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.' %} {% parameter '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' %} {% parameter 'subject' 'Yes' 'Must be a valid string' 'The subject of your email' %} {% parameter 'text' 'No' 'API call must include at least one of the text or html parameters.' 'The plain text content of your email message.' %} {% parameter 'html' 'No' 'API call must include at least one of the text or html parameters.' 'The HTML content of your email message.' %} {% parameter 'from' 'Yes' 'Must be a valid email address from your domain' 'This is where the email will appear to originate from for your recipient' %} {% parameter '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].' %} {% parameter 'ccname' 'No' 'Must be a valid email address' 'This is the name be appended to the cc field.' %} {% parameter '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].' %} {% parameter 'bccname' 'No' 'Must be a valid email address' 'This is the name appended to the bcc field.' %} {% parameter 'fromname' 'No' 'Must a valid string' 'This is the name appended to the from email field. IE - Your name or company name' %} {% parameter 'replyto' 'No' 'Must be a valid email address' 'Append a reply-to field to your email message' %} {% parameter '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');' %} {% parameter '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' %} {% parameter '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. %} {% parameter '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"}' %} {% endparameters %}

{% apiexample mail POST https://api.sendgrid.com/api/mail.send api_user=your_sendgrid_username&api_key=your_sendgrid_password&to=[email protected]&toname=Destination&subject=Example_Subject&text=testingtextbody&from=[email protected] %} {% response json %} { "message": "success" } {% endresponse %} {% response xml %} success

{% endresponse %} {% endapiexample %}

{% anchor h3 %} Call: Send to Multiple Recipients {% endanchor %}

{% apiexample multiple POST https://api.sendgrid.com/api/mail.send 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] false %} {% response json %} { "message": "success" } {% endresponse %} {% response xml %} success

{% endresponse %} {% endapiexample %}

{% anchor h3 %} Call: Sending with a CC and CCname {% endanchor %}

{% apiexample cc POST https://api.sendgrid.com/api/mail.send 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] false %} {% response json %} { "message": "success" } {% endresponse %} {% response xml %} success

{% endresponse %} {% endapiexample %}

{% anchor h3 %} Call: Sending with a BCC and BCCname {% endanchor %}

{% apiexample bcc POST https://api.sendgrid.com/api/mail.send 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] false %} {% response json %} { "message": "success" } {% endresponse %} {% response xml %} success

{% endresponse %} {% endapiexample %}

{% anchor h3 %} cURL Examples {% endanchor %}

{% anchor h4 %} Send to one email recipient {% endanchor %}

{% codeblock lang:bash %} curl -d 'to=[email protected]&toname=Destination&subject=Example Subject&text=testingtextbody&from=[email protected]&api_user=your_sendgrid_username&api_key=your_sendgrid_password' https://api.sendgrid.com/api/mail.send.json {% endcodeblock %}

{% anchor h4 %} Send to multiple email recipients {% endanchor %}

{% codeblock lang:bash %} curl -d 'to[]=[email protected]&toname[]=Destination&to[]=[email protected]&toname[]=Destination2&subject=Example Subject&text=testingtextbody&from=[email protected]&api_user=your_sendgrid_username&api_key=your_sendgrid_password' https://api.sendgrid.com/api/mail.send.json {% endcodeblock %}

{% anchor h4 %} Send a test with attachment {% endanchor %}

{% codeblock lang:bash %} 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="testing html body"
-F from=[email protected] -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password
-F files[attachment.gz][email protected] {% endcodeblock %}

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

{% anchor h4 %} Send a test specifying the file content type by appending ';type=' to the file name {% endanchor %}

{% codeblock lang:bash %} 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="testing html body"
-F from=[email protected] -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password
-F files[attachment.pdf][email protected];type=application/pdf {% endcodeblock %}

{% anchor h3 %} Raw HTTP Dump {% endanchor %}

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

{% codeblock %} POST /api/mail.send.json HTTP/1.1 {% endcodeblock %}

{% codeblock %} Host: sendgrid.com

Accept: /

Content-Length: 999

Expect: 100-continue

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

HTTP/1.1 100 Continue