Inbound Email Routing in PHP

Written by Orlando Kalossakas

Categories: Email DIY

4 minute read time

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

<?php 
# Uses the autoloader provider by Composer
require 'vendor/autoload.php';
# Defines the namespace we're going to use
use MailgunMailgun;
# Define some constants such as APIKEY
$CONST_APIKEY = "key-a65gfd4gdf65gd4fgdfgf196";
$CONST_RECIPIENTEXP = "*@sampleprovider.com";
$CONST_PRIORITY = 0;
$CONST_FORWARDTO = "http://samplewebsite.com/webhook";
$CONST_DESCRIPTION = "Sample-Description";

# Starts the client
$mgClient = new Mailgun($CONST_APIKEY);

# Configure the variables to be passed on to Mailgun through a POST request that creates a route
 $result = $mgClient->post("routes", array(
    'priority'    => $CONST_PRIORITY,
    'expression'  => 'match_recipient("'. $CONST_RECIPIENTEXP.'")',
    'action'      => array('forward("'.$CONST_FORWARDTO.'")', 'stop()'),
    'description' => $CONST_DESCRIPTION
));
?>

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

<?php 
# Uses the autoloader provider by Composer
require 'vendor/autoload.php';
# Defines the namespace we're going to use
use MailgunMailgun;
# Define some constants such as APIKEY
$CONST_APIKEY = "key-a8qsdfgds45gdfgdf9f91d17b7f196";

# Starts the client
$mgClient = new Mailgun($CONST_APIKEY);

# Configure the variables to be passed on to Mailgun through a POST request that creates a route
$result = $mgClient->get(
"routes", array('skip' => 0, 'limit' => 10)
);
#Let's print some output, ofcourse you can iterate the object $result to find more information regarding the routes!
print "<strong>The whole object:</strong>"; 
print "<br>";
print_r($result);
print "<br>";
print "<strong>The expression assigned to the first route:</strong>"; 
print "<br>";
print $result->http_response_body->items[0]->expression;
print "<br>";

?>

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:

Content-Type    
Date    
From    
In-Reply-To    
Message-Id    
Mime-Version    
Received    
References    
Subject    
To    
X-Envelope-From    
X-Mailgun-Incoming    
X-Received    
body-html    
body-plain    
domain    
from    
message-headers    
message-url    
recipient    
sender    
signature    
stripped-html    
stripped-signature    
stripped-text    
subject    
timestamp    
token    

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

<?php
$content = $_POST['stripped-text'];
$file = 'output.txt';
file_put_contents($file, $content, LOCK_EX);
?>

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!

Modified on: March 13, 2019

Stay up-to-date with our blog & new email resources

We'll let you know when we add new email resources and blog posts. We promise not to spam you.