Inbound Email Routing In PHP

Sending email is certainly the most known feature to Mailgun’s users but Mailgun can do much more than just sending emails and tracking analytics. When people ask me what I love most about Mailgun, I almost always say how intuitive and well documented the API is. There is this one particular feature, however, I like to tell people about and that’s the inbound email routing and parsing system, also known as “Routes” in the control panel.

Inbound email routing means that you can set up Mailgun to receive emails on your behalf. You can set it up with a whole domain or a sub-domain of your choice. I think using a subdomain is the way to go because you can only set up one service to receive your emails at one time. This means that you cannot use your email client and Mailgun’s inbound feature on the same domain. For this reason, I have a set up like the following:

• orlando@domain.com: That I use with a normal email client

• robots@inbound.domain.com: That handles other emails workflows through the Mailgun inbound API.

Once an email is received, Mailgun can do a few things with it – send it to another endpoint of your choice, redirect it to another email, store it so you can process it later.

Cool! What do I use it for?

Process all attachments!

What if you could use emails to build an app that received attachments and automatically sent them to your online storage account (like Dropbox, google drive or similar)?

What if this email could understand who is sending you the attachments, what they contained and sort them accordingly?

Well, good news, with Mailgun’s email routing you can!

You do this by specifying a filter on a domain or sub-domain. To get started visit the routes in the control panel and remember you’re going to need to change your domain’s DNS settings accordingly so that your MX records point to Mailgun.

A route is composed of a filter, an action, a description to make it easier for humans to understand what the route does and a priority.

A filter is one of the following types:

• match_recipient(pattern): Where patterns is a regular expression of an email address

• match_header(header, pattern): Where the header is a (MIME header) and the pattern a regular expression

• catch_all(): Usually lowest priority as it will forward on any incoming email

You can specify the above filter to have actions dynamically if the filter matches an address specified a resulting action will occur. A list of actions can be found below, keep in mind you can have more than one action at any given time:

• Forward(): Forwards the email to another email address or URL

• Store(): Saves the matched email on Mailgun’s server for up to 3 days for later or delayed usage.

• Stop(): Simply halts the chain of actions. It is required to prevent the message from being processed further by other actions. (Will get to this later in more details)

Prioritize routes by giving them priority accordingly.

• Low number = High Priority

• High number = Low Priority

Routes with the same priority are given priority based on creation date.

After setting up your domain or sub-domains DNS to forward emails to Mailgun as explained in the documentation with the settings given on your domain page you can begin the fun part!

Creating, editing, deleting routes in PHP

After installing the PHP library we can create a new file called createRoutes.php

How about listing all the routes to investigate which ones you’ve have already created, programmatically, and eventually editing them.

At this point, we’ve successfully created a route. Every time Mailgun receives an email from someone *@sampleprovider.com – Mailgun will take its message and send a web-hook with its content to http://samplewebsite.com/webhook.

Now on my side (assuming http://samplewebsite.com/webhook is my server) I want to capture the content of the webhook that has been sent when a filter catches an incoming email.

Mailgun sends all kind of headers, most are listed below:

Let’s assume we want to write to a file the body of the message stripped from all HTML, newlines, and returns.

The following code will be executed by PHP when the webhook sent by Mailgun is received and will write the content of the request body (in this case I picked stripped-text but it could have been any of the above) to a file called output.txt

As you can see, the options from here are endless!

If you are interested in learning more about the inbound email routing functionalities, head to the documentation page or feel free to ask questions or comment here or on Twitter.

Happy Sending!