Send an email with SendGrid by creating an account and an API key, then making a POST request to the v3 mail send endpoint with your key in the Authorization header and a JSON body holding the recipient, sender, subject and content. SendGrid's own guide uses cURL, and its libraries cover PHP, Python, Node.js, Java, C#, Go and Ruby.
This route is the API, not the dashboard
There's more than one way to send through SendGrid, but the route SendGrid documents step by step for a first email is its Web API, called with cURL from your terminal or through one of its official libraries. That's what this guide covers. I'm not going to describe the dashboard's campaign screens here. If you'd rather not touch code at all, a connector such as Zapier is the better starting point.
What you need first
- A SendGrid account.
- An API key. Basic Authentication is no longer accepted, so a username and password won't work.
- cURL installed, or one of the official libraries for PHP, Python, Node.js, Java, C#, Go or Ruby.
Anatomy of the request
| Part | What goes in it |
|---|---|
| Method and address | POST to api.sendgrid.com/v3/mail/send |
| Authorization header | Your API key |
| Content type | JSON, because POST and PUT payloads must be JSON |
| personalizations | Who the email goes to |
| subject and content | The subject line and the body |
| from and reply_to | The sender address and where replies should go |
Every Web API v3 request goes to the same host, api.sendgrid.com/v3. SendGrid recommends pointing at that address rather than hardcoding IP addresses, which can change without notice.
Sending your first message
- Create your SendGrid account.
- Create an API key and copy it somewhere safe.
- Build the request: a POST to the mail send endpoint, with an Authorization header carrying your key and a JSON content type.
- In the JSON body, put the recipient in personalizations, then add a subject, the content, and the from and reply_to addresses.
- Run the call from your terminal.
- Check the recipient's inbox, and the spam folder too if you haven't set up Sender Authentication.
Use your own address as the recipient for the first test. It's the quickest way to see what a customer would see.
Size limits and the spam folder
Twilio SendGrid Docs point out two things that make a first send look broken when it isn't. The total message size, including headers and all attachments combined, shouldn't exceed 20MB. That's the whole email, not each attachment. And if Sender Authentication isn't set up, your test email may land in spam, so a missing message is often sitting one folder over.
If you plan to send real emails to customers, set up Sender Authentication before you go further. It's the difference between a test that works and a campaign that reaches inboxes.
Moving from cURL to your app
cURL is perfect for a first test, but your website or app will want a library. Pick the one for your language, keep the API key out of your code by storing it in an environment setting, and send the same fields you used in the test. If you're deciding how your systems should talk to each other more broadly, my explainer on APIs versus webhooks helps.
Keeping your keys tidy
Make a separate API key for each app or website that sends email, and name each one after where it's used. That way, if a developer leaves or a site is retired, you can delete one key without breaking everything else. Never paste a key into a shared document or a chat message, and treat it like a password.
Other sending APIs
Mailgun says on its send product page that you can send through an SMTP relay or a RESTful API.
Postmark has developer docs for sending a single email or batches with its API, with libraries including Node.js, Python and PHP.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
My comparison of SendGrid and Mailgun looks at how the two differ for small businesses.
The advice I'd give before you send to customers
Send your first test to yourself with cURL, check spam, then set up Sender Authentication before anything goes to a customer. Keep the whole message under 20MB, store your API key safely, and move to the official library for your language once the test works.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
Do I need code to send with SendGrid?
SendGrid's guide covers the API with cURL, and it doesn't cover a no-code route.
How big can an email be?
The total message size, including headers and attachments, shouldn't exceed 20MB.
Can I use a username and password?
No. Basic Authentication is no longer accepted.
Which languages have libraries?
PHP, Python, Node.js, Java, C#, Go and Ruby.
Why did my test land in spam?
You may not have set up Sender Authentication yet.
