Forwarding Inbound Email with Heroku

Duncan Rance
Apr. 27, 2016 by Duncan Rance

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


  • Can this be used to forward bounces/spam complaints to another mailbox?

  • Hi,

    We have a sample app that listens for out-of-band bounce webhooks and sends a simple DSN message to your chosen mailbox:

    This could be extended to listen for spam webhook calls.


Related Content

Don't Commit: A Guide to Avoiding Distractions While Coding

Manager of Software Engineering - Analytics, Robert Wenner, shares his tips and tricks for avoiding distractions while coding.

read more

On-Premises and Cloud: Putting the Pieces Together

In our upcoming webinar, hear directly from our team of on-premises experts about how to confidently use both on-prem and cloud email solutions.

read more

New Events API: More Powerful, Flexible Events Searching

Our new Events Search API's searching capabilities allow you to access the raw event data associated with the messages you send via SparkPost.

read more

Get started and start sending

Try SparkPost and see how easy it is to deliver your app’s email on time and to the inbox.

Try Now

Send this to a friend