Forwarding Inbound Email with Heroku

What’s This? Forwarding Inbound Email?

We have been asked in our community Slack channel about forwarding inbound email messages via SparkPost to a mailbox. Our product folks are looking into adding it to our roadmap as a first-class feature of SparkPost, but in the meantime, I’ve put together a sample app that uses Heroku to provide similar functionality using today’s API endpoints.

The code can be found in GitHub, in the SparkPost/sp-forwarding-service repository.

Heroku has a great feature called the “Deploy to Heroku” button. This makes it super easy to get set up with the Forwarding Service. Either head on over to the repository’s README or just click here:

Let’s Deploy the Service!

After you’ve hit the big purple button you’ll see a Heroku sign-up screen. If you’re a new user, sign up! If you’re already a Heroku user, just click the “Log In” link at the bottom of the page.

Once you’ve signed up or logged in, you’ll get to a simple configuration page. Here you can add a name for the application. That is optional—if you leave it blank, Heroku will invent some funky name for you like  mesmerizing-badger-54321.

There is a choice of which region to run the app in. Just choose United States here, as that’s where SparkPost’s servers are!

Now comes a couple of important “config vars” to set up. First the FORWARD_FROM, which will be the email address the recipient will see as the sender of the message. The default value uses the sandbox domain that is limited to 50 messages for the lifetime of your account, so change this for anything but a demo. The domain used here must be verified from the SparkPost UI before you can begin to use the app.

Next comes FORWARD_TO. Set this to the address of the mailbox where you want to receive your forwarded messages.

Now you can hit the “Deploy for Free” button to activate the code from GitHub.

How Do I Choose Which Mails Get Forwarded?

That’s a great question. You might think we’re done with configuring this thing, but no, there is one more step.

At the bottom of the page you will see “Your app was successfully deployed.” Hit the button marked “View” just under this to be taken to the app’s setup page.

Here you will see that the page is checking for an inbound (“relay”) webhook. Of course it won’t find one, because you’ve not set it up yet. Hang on; we’ll get to that.

Before you create that webhook, you’ll need a domain name that has been set up in DNS to have MX records pointing to SparkPost. Specifically, you’ll need to add the following three MX records for your domain:


Once these records have been added to your domain, you can go back to the app’s set up page. Type your domain name into the appropriate box and hit “Add domain.” This tells the app to create both an inbound domain and a relay webhook in SparkPost.

That’s it! Messages sent to any mailbox @ your inbound domain will be directed to SparkPost. SparkPost will trigger a POST to the Forwarding Service. Then, this forwarding service app takes the webhooks data and uses SparkPost’s Transmission API endpoint to deliver messages to your configured recipient.

The flow looks something like this:

Forwarding Inbound Email with Heroku Diagram

As you can see, the forwarding service is pretty simple, but it gets the job done.

What’s Next? Have Ideas to Add to the Forwarding Service?

Start sending! If you want to see the dashboard of the SparkPost account the app is using, head over here for instructions.

Have ideas for improving the forwarding service or want to add a feature? Swing by GitHub to raise an issue or submit a PR. Your contributions to community projects really make SparkPost even more awesome.

I hope you find this service for forwarding inbound email with SparkPost useful. I’d love to hear how you use it!


Dev Survival Guide Blog Footer