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:
- email@example.com: That I use with a normal email client
- firstname.lastname@example.org: 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
<?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->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
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
<?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.
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.