SendGrid Inbound Parse with Express

This post will be a quick guide to using SendGrid Inbound Parse with Express.js. By the end of this post you’ll be able to parse incoming emails and inspect the data. This will be great for a helpdesk type application.

Prerequisites

• SendGrid Account
• Your own domain
• Node.js
• Ngrok (testing tool)

Here’s my GitHub repo express-sendgrid-inbound-parse if you want to skip Creating the project part.

Creating the project

Let’s start with creating our express app. Find a directory to add your project to, then…

• mkdir express-sendgrid-inbound-parse
• cd express-sendgrid-inbound-parse
• touch index.js
• npm init -y to create a default package.json file
• npm install express multer
• npm install nodemon --save-dev
• code . to open VS Code

Below is the startup file index.js and that’s all we need to begin.

A very straight forward index.js , we use multer to parse the body and attachments, and use a POST endpoint.

You can now run nodemon index.js to boot the server and make http://localhost:3000/api/parse available locally.

Setting up ngrok

Ngrok exposes local servers behind NATs and firewalls to the public internet over secure tunnels.

Create a FREE account here and follow the setup process for your OS.

Once you’ve finished setting up, you should be able to run ngrok http 3000 , ngrok will give you a temporary url which will forward requests to localhost:3000 .

Both http and https are available

Going by the example above, you can now access the local API by using http://58d59d11d35d.ngrok.io/api/parse.
This will have to be a POST request for it to hit the endpoint. (Postman works but will cause a 500 error)

Next we set up SendGrid.

Setting up SendGrid

Head over to sendgrid.com and create a free account…

When you have created a SendGrid account, you will have to add your own domain to be used with Inbound Parse.

Go to, Settings > Sender Authentication.

Once you’ve verified your domain, we can proceed with Inbound Parse.

Go to, Settings > Inbound Parse.

Click Add Host & URL

Click the blue button to add domain details

Next, add a sub-domain of parse, select your verified domain and add a Destination URL which is the URL generated with ngrok, http://58d59d11d35d.ngrok.io/api/parse, yours will be different.

The Destination URL is where Inbound Parse posts the email data to, this is why the express application exposes the POST http verb.

Click Add to finish.

Setting up email domain configuration

Note, this URL will change each time you create a new connection. The paid plans give you access to create your own domain my-domain.eu.ngrok.io .

Our email domain setup

One more thing 😊

To begin processing email using SendGrid’s Inbound Parse Webhook, you will have to setup MX Records, choose the hostname (or receiving domain) that will be receiving the emails you want to parse, and define the URL where you want to POST your parsed emails. — Setting up The Inbound Parse Webhook

Go to your domain registrar and assign the MX record a priority of 10, and point it to the address: mx.sendgrid.net.

Example of my MX record

With that all set, let’s test.

Testing Inbound Parse

• Make sure you have your project running on http://localhost:3000

Express app running on localhost:3000

• Ngrok needs to be connected to forward the request to your localhost

Ngrok exposing localhost:3000

• SendGrid Destination URL needs to point to the ngrok forwarding URL

SendGrid configured

Now send an email to anything@parse.your-domain.com , for me it is test@parse.gymdummy.com

Now wait for it to hit your endpoint….

…

…

When successful,

Ngrok will show the endpoint was hit with a 200 OK

Successful request to our endpoint

The terminal where you ran the application will have logged each property of the request body.

Snippet of the request body logged to the console

We did it! 😁👍

Conclusion

That’s it, you can now parse incoming emails. To recap, we’ve setup our project, which runs on localhost port 3000.
We then setup ngrok, which gives us a public facing URL forwarding to our localhost.
Finally, we configured SendGrid’s Inbound Parse to forward any emails to our domain, which gets parsed on our localhost through ngrok’s public URL.

Don’t forget your MX records, it will not work unless it’s configured.

A little tip, you can forward emails to your SendGrid Inbound Parse address.
For example, create a new email address, say test@your-domain.com which forwards to anything@parse.your-domain.com . Keeps it tidy.

Thank you for reading,

Happy coding!