Faros email notification for a new message
Example Faros email for new messages

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 webhook URL. So this is a short guide to setting up Inbound Parse in a NodeJS application.

Step 1

Add a new MX record to your DNS that points to SendGrid. This will allow SendGrid 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 emails sent to this domain will be routed through SendGrid and to your API.

Faros MX record for SendGrids Inbound Parse
Faros MX record for SendGrids 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. More details can be found here.

Step 2

Add a webhook to Inbound Parse in SendGrid as documented here. 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

Setup 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.

Code available here

Step 4

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

Parse the contents 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).

Code available here

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!