EMAIL / LESSON 06

Setting Up SendGrid.

Create a SendGrid account, make an API key, verify your sender and send your first email from Node.js

Written by Andrew Lee JenkinsPublished Oct 5, 202612 min readFree lesson

Time to get SendGrid working for real. By the end of this lesson you'll have an account, an API key tucked away safely, a verified sender and your first email sent from a few lines of Node.js.

Step by Step Setup

Go through these in order. Every step leans on the one before it.

Step 1. Create Your Account

Head to twilio.com/en-us/sendgrid and sign up. New accounts start on a free trial, so you can follow along without paying anything.

SendGrid's official quickstart also asks you to turn on two factor authentication, which means signing in takes your password plus a code from your phone. Just do it now and get it over with.

Step 2. Create an API Key

An API key is the password your code uses to talk to SendGrid. To make one, go to Settings, then API Keys, and click Create API Key.

Give it a clear name, like "My App Production"
Choose its permissions

The safest habit is giving a key ONLY the access it needs. SendGrid's quickstart says to create a restricted key with Mail Send set to Full Access. On the API Keys page, that's the Custom Access option, where you pick access one area at a time. Your app can then send email and do nothing else. The other choices, Full Access for everything and Billing Access, are way more than a sending app needs.

Click to create it, and SendGrid shows you the key.

Step 3. Store the Key in an Environment Variable

SendGrid's docs are pretty blunt about this one. Treat your API key like a password, and never put it in your code or commit it to a repository like GitHub.

Keep it in an environment variable instead. That's a named value living outside your code that your app reads when it runs. Here's the setup from the official @sendgrid/mail README, run inside your project folder.

Example

echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
echo "sendgrid.env" >> .gitignore
source ./sendgrid.env

Line by line, here's what that does.

Saves your key into a file called sendgrid.env
Adds that file to .gitignore so Git never uploads it
Loads the key into your current terminal session

Swap YOUR_API_KEY for the real key you copied. Your code will now find it as process.env.SENDGRID_API_KEY.

Proving Who You Are

Before SendGrid sends a single thing, it needs to know you're allowed to use the "From" address. SendGrid calls this a Sender Identity, which is the address your recipients see as the sender. Skip this part and your first send fails with a 403 Forbidden error.

There are two ways to prove it.

Step 4. Quick Option, Verify a Single Sender

This one's good for testing. Go to Settings, then Sender Authentication, and click Verify a Single Sender.

Fill out the form. It asks for a From Name, From Email Address, Reply To, your company address and a nickname. Click Create, then open the inbox for that From address and click the link SendGrid emails you. That address is now verified.

Step 5. The Proper Option, Authenticate Your Domain

For real sending, you authenticate your whole domain, like yourapp.com. SendGrid's quickstart lists this as a required step, and its docs note that domain authentication is also required to upgrade from a free account.

You'll actually SEE a benefit too. Without it, some inboxes show "via sendgrid.net" next to your From address. Domain authentication gets rid of that tag and makes your mail look more trustworthy to inbox providers and to actual humans.

So how does it work? Email authentication runs three checks, and each one lives as a record in your domain's DNS settings.

SPF is a list of which servers are allowed to send email for your domain. The receiving server checks that the email came from a server on that list.
DKIM adds a hidden digital signature to every email. The receiving server checks the signature to make sure nothing got changed along the way.
DMARC tells the receiving server what to do with an email that fails those checks, like deliver it anyway, send it to spam or reject it.

SendGrid's docs also point out that big inbox providers like Gmail and Yahoo require DMARC policies for bulk senders. So this step matters more every single year.

To set it up, go to Settings, then Sender Authentication, and start the domain authentication flow.

Choose your DNS host from the dropdown (the company where you manage your domain)
Enter the domain you want to send from
SendGrid gives you a set of DNS records to copy
Add those records at your DNS host
Come back to SendGrid and click Verify

The records SendGrid hands you depend on your settings. With its default automated security turned on, you get CNAME records that cover SPF and DKIM plus a TXT record for DMARC. Copy them EXACTLY as shown.

Side note, I got tired of squinting at DNS records by hand, so one of the free tools I put out is an email deliverability checker that looks at a domain's SPF, DKIM and DMARC for you. Running your domain through something like that after you add the records is a nice sanity check.

Sending Your First Email

Key stored, sender verified. You're ready to send.

Step 6. Install the Library

In your Node.js project folder, install the official mail package.

Example

npm install --save @sendgrid/mail

Step 7. Write the Code

Create a file called index.js and paste in this example from SendGrid's official Node.js quickstart.

Example

const sgMail = require('@sendgrid/mail')
sgMail.setApiKey(process.env.SENDGRID_API_KEY)

const msg = {
  to: 'test@example.com', // Change to your recipient
  from: 'test@example.com', // Change to your verified sender
  subject: 'Sending with SendGrid is Fun',
  text: 'and easy to do anywhere, even with Node.js',
  html: '<strong>and easy to do anywhere, even with Node.js</strong>',
}

sgMail
  .send(msg)
  .then((response) => {
    console.log(response[0].statusCode)
    console.log(response[0].headers)
  })
  .catch((error) => {
    console.error(error)
  })

Here's what each piece is doing.

require('@sendgrid/mail') loads the library
setApiKey hands it your key, read from the environment variable and never typed into the file
msg is the email itself. to is who gets it, from has to be your verified sender, and subject is the subject line
text and html are two versions of the body. Email apps that can show formatting use the HTML version, and the rest fall back to plain text
send sends it, then logs the result or the error

Change to to your own email address and from to the sender you verified in Step 4 or Step 5.

Step 8. Run It

In the same terminal where you loaded your key, run the file.

Example

node index.js

If it worked, you'll see 202 printed first. That status code means SendGrid accepted your email for delivery. Go check your inbox, and peek in your spam folder too just in case.

TL;DR

Sign up for SendGrid and turn on two factor authentication first
Create an API key under Settings, then API Keys, and give it only Mail Send access
SendGrid shows the key once, so copy it right away and keep it in an environment variable, never in your code
Verify a single sender for quick tests, and authenticate your domain for real sending
SPF lists who's allowed to send for your domain, DKIM signs each email and DMARC says what to do when checks fail
Install @sendgrid/mail, call setApiKey, then send a message with to, from, subject, text and html
A 202 means SendGrid accepted your email, and a 403 usually means your sender isn't verified

Loading the lesson…

Loading activities…