The Mail Send endpoint provides a powerful and intuitive interface for sending email.
The endpoint accepts a JSON object that specifies the details of the email(s) to be sent. This includes not only the basic elements like the sender, recipient, subject, and content, but also more advanced features like personalizations, attachments, and dynamic templates.
SendGrid's v3 Web API uses https://api.sendgrid.com for global users and subusers and https://api.eu.sendgrid.com for regional subusers in the EU.
If you have the flexibility, it's best to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour.
Scheduling email to avoid peak times, for example, scheduling at 10:53 rather than 11:00, can result in lower deferral rates due to the reduced traffic during off-peak times.
In addition to passing plain text or raw HTML to SendGrid to construct your messages, you can make use of our Dynamic Templates. See How to Send an Email with Dynamic Templates for more information about adding templates and dynamic data to your emails.
Mail body compression is available to some high volume accounts. Mail body compression works by setting up a JSON payload as defined in the Mail Send endpoint reference, then compressing it with gzip (the gzip file can be no more than 30mb).
Gzip will take the JSON payload and compresses it into a gzip file. This means that anything in the JSON payload including the attachments will be compressed. The compressed data must also be less than the 30MB maximum for the email with headers, body, and attachments.
Content-Encoding header, with a value of gzip.
Content-Encoding: gzip--data-binary '@data.json.gz'Using reply_to_list allows senders to include more than one recipient's email address to receive reply messages from the recipient of the email.
reply_to and reply_to_list properties are mutually exclusive. If both are used, the API call will be rejected.reply_to_list object, when used, must have at least an email property and may also contain a name property.reply_to_list should be unique.reply_to_list emails per Mail Send request.There are several rate limitations and restrictions that you should be aware of when using the v3 Mail Send endpoint.
to, cc, and bcc parameters, across each object that you include in the personalizations array.from field.to.name, cc.name, and bcc.name personalizations cannot include either the ; or , characters.For more specific, parameter-level requirements and limitations, please refer to the Mail Send endpoint documentation.
Whenever you make a request to the v3 Mail Send endpoint, your JSON payload is validated before your email is sent. If there are any errors, SendGrid will attempt to identify and return as many issues as possible for each request. For more information, please read our error documentation.
For a more full-featured guide to ensure you build your email program atop a solid foundation, see our Email API Onboarding guide.
Jump to an email quickstart in your programming language of choice for a full guide on how to implement the Mail Send API.
See our open-source helper libraries and tools to integrate with SendGrid quickly.
See the rest of our API reference for more information on how to use the SendGrid v3 Web API's additional features and endpoints.