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:

Deploy
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 sparkpostbox.com 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:

  • rx1.sparkpostmail.com
  • rx2.sparkpostmail.com
  • rx3.sparkpostmail.com

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!

—Duncan

Dev Survival Guide Blog Footer

2 Comments

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

    Reply
  • Hi,

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

    https://github.com/SparkPost/sp-bounce-forwarding-service

    This could be extended to listen for spam webhook calls.

    Regards,
    Duncan

    Reply

Share your Thoughts

Your email address will not be published.

Related Content

Community Spotlight: How Topol Makes Creating Beautiful HTML Email Templates Easy

Building HTML email templates is hard. Learn about the app that Jan Tlapak and Sendmark created for anybody in need of building beautiful HTML emails.

read more

Running Your First Technical Workshop: The "I Have No Idea What I'm Doing" Edition

Running a technical workshop is difficult! Where do you start? How much time do you allot? What audience do you aim for? Cole talks through what he learned.

read more

Introducing Our SendGrid Template Migration Tool

Automatically migrate any SendGrid template over to SparkPost. This open source tool supports both UI- and API-driven email template migration workflows.

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 send up to 100,000 emails per month for free.

Send 100K Emails/Month For Free

Send this to a friend