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

Heads Up: Changes to Error Handling in Transmissions API

Learn about the three major upcoming changes to error handling in our Transmissions API that we're rolling out in January 2019.

read more

Discovering Your Financial Services Competitive Superpower

Learn about financial services' competitive superpower: using email and the cloud to enable great customer experiences and outperform competition.

read more

Support for Google AMP for Email in SparkPost Coming Soon

We’re working with Google to add support for Accelerated Mobile Pages (AMP) for Email to the SparkPost service. Here’s a preview of how it works.

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 Free

Send this to a friend