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.



Share your Thoughts

Your email address will not be published.

Related Content

Burnout: What Happens When You Take On Too Much

Burnout has become a very relevant topic in the tech industry. Our community manager offers several tips on how to avoid being overworked and stressed.

read more

Creating the Next Generation of Interactive Emails with Rebel Mail

Meet our partner, RebelMail! Today they're demonstrating how to use their interactive email API to keep customers engaged with the inbox.

read more

Using the SparkPost Metrics API with C#

Learn how to query the SparkPost API for information and metrics on the emails you’re sending using the C# wrapper and gain valuable insights.

read more

Start sending email in minutes!

The world’s most powerful email delivery solution is now yours in a developer-friendly, quick to set up cloud service. Open a SparkPost account today and get started for free.

Get Started

Send this to a friend