Setting Up SendGrid

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.

1. Give it a clear name, like "My App Production"
2. 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.

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.

1. Saves your key into a file called sendgrid.env
2. Adds that file to .gitignore so Git never uploads it
3. 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.

1. Choose your DNS host from the dropdown (the company where you manage your domain)
2. Enter the domain you want to send from
3. SendGrid gives you a set of DNS records to copy
4. Add those records at your DNS host
5. 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.

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.

const sgMail = require('@sendgrid/mail')
sgMail.setApiKey(process.env.SENDGRID_API_KEY)
 
const msg = {
  to: '[email protected]', // Change to your recipient
  from: '[email protected]', // 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.

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