This post was written by Huey Ly. Huey is a software developer living and working in Xi'an China, home of the Terracotta warriors. He is the co-founder & lead developer for whyyu.com, a language learning app to teach English to Chinese children. In his spare time, he helps charitable organizations take advantage of technology to further their mission. He's also a very brave dancer.

I volunteer part time at the Agape Community Care Association (www.agape.org.cn), an NGO that helps orphans and other disadvantaged people in the Shaanxi province of China. Agape has volunteers and staff from all over the world, and most of their email accounts are hosted at free providers such as Gmail, Hotmail, or Yahoo. Agape wanted each volunteer to have their own @agape.org.cn email address to give the organization more legitimacy locally and internationally, but migrating and consolidating all the mailboxes of such a diverse group proved to be quite a headache. Additionally, the added cost of all the extra mailboxes would put a dent in their already minuscule funding (they only keep 10% of donations for administrative purposes, the rest goes directly to the orphanages and health clinics) . What can they do?

Email forwarding using Routes

Routes allow you to set up a series of rules on how to handle incoming messages, like those sent to @agape.org.cn . Specifically:

[list type="check"]

Which messages to act on (e.g. messages from a particular person or with a particular subject or even all messages)

What you want to do with those messages (e.g. forward it to another email address or POST it to your app)

[/list]

For Agape, I wanted to match on anything sent to a user with an @agape.org.cn address and forward the email to another address, but Mailgun also allows you elect to post the message to your app: Mailgun will either send you the entire unparsed MIME message (if that's your thing) or parse it for you and POST the parsed parameters. In both cases, they'll transcode the message to UTF-8 which is a really nice bonus.

Setting up 100s of Routes at once using the API

Using Mailgun Routes, Agape was able to forward all emails sent to [user]@agape.org.cn addresses to everyone's personal email accounts. No migrations needed! What’s more, the API system allowed us to write a script that quickly imports hundreds of routes quickly and easily, using a .csv file. Let me show you what I mean.

First, we create a .csv file of source and forwarding address separated by commas, one pair per line, like so:

Then simply make sure the script and .csv file are in the same directory (or change $filepath variable to match your .csv file’s filepath) and run the script:

run_importer();

It’s really quite simple. Using the Mailgun Routes API, we were able to quickly add hundreds of forwarding addresses so that Agape employees and volunteers worldwide can easily access their Agape email. Thanks Mailgun!