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 as its base URL.
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.