Example Faros email notification for a new message
Example Faros email content for new messages (parsed email)

Possibly the most-requested feature from our hosts on Faros has been the ability to reply to messages via email. Anyone who has used Craigslist knows about this feature. Instead of going to a website or application to respond to a message, you simply reply to the email.

While it may sound as simple as POSTing to an API to create the message, making this a seamless process for the user involves a lot of moving parts.

Since we use SendGrid to send all of our emails we decided it would be best to stick with them for the inbound emails. Their documentation is limited because all that’s really done on SendGrid is to add the inbound parse webhook URL. So this is a short guide to setting up SendGrid Inbound Parse in a NodeJS application.

Step 1: Add a DNS Record for SendGrid

Add a new MX record to your DNS that points to SendGrid. This will allow SendGrid Parse to intercept emails and forward them to your API. Create the record for a subdomain that you want emails to be sent to and point it to 10 mx.sendgrid.net. All incoming emails sent to this domain will be routed through SendGrid and to your API.

Sendgrid inbound parse MX record
Faros MX record for SendGrid Inbound Parse

For example, we used Google Domains to add the MX record for a m.gofaros.com subdomain. This means any email with the form anything@emails.gofaros.com will be routed through SendGrid.

Sendgrid inbound parse add host and url

Step 2: Add a Webhook to Inbound Parse

Add a webhook to Inbound Parse in SendGrid. First, click Add Host & Url in the top-right hand corner. Next, enter your desired subdomain along with your site’s domain. Be sure to use the previous domain you made in your MX record and an endpoint on your API that will receive the emails. Lastly, enter the API endpoint (Destination URL) that the email payload will be sent to.

Step 3: Parse the Webhook

Set up your API to receive the webhook. Make sure you correctly parse it or you won’t be able to read the contents. We use multer to parse the body, it’s added before the main body parsing in order to custom parse it.

SendGrid API webhook using multer screenshot
View the SendGrid parse code on GitHub

Step 4: Parse the JSON

The last step is the trickiest, yet most important — parsing the POST request you receive from SendGrid.

Parse the JSON and make the necessary associated updates in your database. The below snippet provides a simplified overview of what our process looks like (stripped of error handling and method implementations).

Parsing SendGrid post response
View the code to parse the JSON on GitHub

There are a few key points here:

Security - properly verify the sender of the message. We attach signed keys to all of our emails in order to securely associate the message and its sender.

Idempotence - only process an email once. We store every processed email with the date and contents to confirm it’s the first time we’ve received it.

Association - use a signed key to verify the user and to associate the response to the original message. This can be done by including the original message ID in the contents of the key.

Have any feedback? Send us a message!