Receiving, Forwarding,and Storing Messages

Introduction to Receiving, Forwarding and Storing Messages

Routes

Route Filters

Route Actions

Receiving Messages via HTTP through a forward() action

Storing and Retrieving Messages

Credentials

Spam Filter

Introduction to Receiving, Forwarding and Storing Messages

Mailgun will allow you to receive emails through Routes, which will perform action that can include:

• Forwarding email to a different email address
• POSTing the data in the email to a URL
• Storing the email temporarily to subsequent retrieval through a GET request

Routes

You can define a list of routes to handle incoming emails. This idea of routes is borrowed from MVC web frameworks like Django or Ruby on Rails: if a message matches a route expression, Mailgun can forward it to your application via HTTP or to another email address or store the message temporarily (3 days) for subsequent retrieval.

You can define routes visually by clicking the Receiving tab in the Control Panel, or programmatically using the Routes API. For more on setting up Routes, see How Do I Setup a Route?.

A Route is a pair of filter+action. Each incoming message is passed to a filter expression, and if it evaluates to true, the action is executed.

Each Route can be assigned a priority, and are evaluated in the order of priority, with lower numbers having a higher priority. By default, all Routes are evaluated (even if a higher priority Route is triggered). To avoid this action, you can use a stop() action (see below).

Route Properties

Route Filters

Route filters are expressions that decide when an action is triggered. A filter is created based on the recipient of the incoming email, the headers in the incoming email or use a catch-all filter. Filters support regular expressions in the pattern to give you a lot of flexibility when creating them.

Match Recipient(pattern)

Matches the SMTP recipient of the incoming message against the regular expression pattern. For example, this filter will match messages going to foo@bar.com:

match_recipient("foo@bar.com")

You can use Python-style regular expressions in your filter. For example, this will match all messages coming to any recipient at @bar.com:

match_recipient(".*@bar.com")

Another example, handling plus addressing for a specific recipient:

match_recipient("^chris\+(.*)@example.com$")

Mailgun supports regexp captures in filters, which allows you to use captured values inside of your actions. The example below captures the local name (the part of email before @) and passes it as a mailbox parameter to an application URL:

route filter : match_recipient("(.*)@bar.com")
route action : forward("http://myhost.com/post/?mailbox=\1")

You can use named captures as well:

route filter : match_recipient("(?P<user>.*?)@(?P<domain>.*)")
route action : forward("http://mycallback.com/domains/\g<domain>/users/\g<user>")

Match Header(header,pattern)

This is similar to match-recipient, only instead of looking at a message recipient, it applies the pattern to an arbitrary MIME header for the message.

The example below matches any message with a word "support" in its subject:

match_header("subject", ".*support")

The example below matches any message against several keywords:

match_header('subject', '(.*)(urgent|help|asap)(.*)')

The example below will match any messages deemed spam (if spam filtering is enabled):

match_header('X-Mailgun-Sflag', 'Yes')

matchrecipient(pattern) AND matchheader(header, pattern)

The example below will match any recipient for a domain, then match if the message is in English:

match_recipient('^(.*)@example.com$') and match_header("Content-Language", "^(.*)en-US(.*)$")

catch_all()

Will create matches if no proceeding routes matched. Usually, you need to use it in a route with a lowest priority, to make sure it evaluates last.

Route Actions

If a route expression is evaluated to true, Mailgun executes the corresponding action. Currently you can use the following three actions in your routes: forward(), store() and stop().

Forward(destination)

Forwards the message to a specified destination, which can be another email address or a URL. A few examples:

forward("mailbox@myapp.com")
forward("http://myapp.com/messages")

You can combine multiple destinations by separating them with a comma.

forward("http://myapp.com/messages, mailbox@myapp.com")

Store(notification endpoint)

This temporarily stores the message (for up to 3 days) on Mailgun's servers so that you can retrieve it later. This is helpful for large attachments that may cause time-outs, or if you want to retrieve them later to reduce the frequency of hits on your server.

When you specify a URL, Mailgun will notify you when the email arrives along with a URL which you can use to retrieve the message:

store(notify="http://mydomain.com/callback")

If you don't specify a URL with the notify parameter, the message will still be stored and you can get the message later through the Messages API. You can see a full list of parameters we will post/return to you below.

Stop()

Without a stop() action executed, all lower priority Routes will also be evaluated. This simply stops the priority waterfall so the subsequent routes won't be evaluated.

Receiving Messages via HTTP through a forward() action

When a specify a URL from your application as a route destination through a forward() action, Mailgun will perform an HTTP POST request into the URL using one of the two formats:

• Fully parsed : Mailgun will parse the message, encode it into UTF-8, process the attachments, and attempt to separate quoted parts from the actual message. * Preferred Option.
• Raw MIME : The message will be posted as-is. You are responsible for parsing MIME. To receive raw MIME message, the destination URL must end with mime.

For Route POSTs, Mailgun listens to codes from your server and reacts accordingly:

If a 406 error code is not returned and your application is unable to process the webhook request, Mailgun will attempt to retry (other than for delivery notification) in intervals for 8 hours before stopping to try. The intervals are 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, and 4 hours.

You can use these two tables of HTTP parameters to determine what you can expect to be posted into your applications through a forward() action.

Parsed Messages Parameters

Example: Ruby on Rails requires a special syntax to post params like that: you need to add [] to a key to collect its values on the server side as an array.

Below is a Ruby on Rails example of obtaining MIME headers via message-headers parameter:

MIME Messages Parameters

Storing and Retrieving Messages

When storing an email through a store() action in a Route, you can choose to be notified when the message is stored by including a URL with the notify parameter when setting up the store action or you can retrieve the message later by searching for the message through the Events API and retrieving it through the Messages API.

When you set a URL to be posted when the message is received:

(store(notify="http://mydomain.com/callback") or retrieve the message later through a GET request to the Messages API, the following parameters are posted/returned in JSON.

If at least one attachment is written, then the resulting body will have a multipart/form-data content type, otherwise it will have an application/x-www-form-urlencoded content type.

Alternatively, you can choose the following parameters when the Accept header is set to message/rfc2822

Credentials

Mailgun gives you the ability to programmatically create SMTP credentials which can be used to send mail. SMTP credentials can be used to relay email, through Mailgun, using the SMTP protocol.

Listing all credentials:

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getCredentials() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/domains/" + YOUR_DOMAIN_NAME + "/credentials")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}

Sample response

{
  "total_count": 2,
  "items": [
    {
      "size_bytes": 0,
      "created_at": "Tue, 27 Sep 2011 20:24:22 GMT",
      "mailbox": "user@samples.mailgun.org"
      "login": "user@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Thu, 06 Oct 2011 10:22:36 GMT",
      "mailbox": "user@samples.mailgun.org"
      "login": "user@samples.mailgun.org"
    }
  ]
}

Creating a new SMTP credential:

import com.mailgun.api.v3.MailgunDomainsApi;
import com.mailgun.model.ResponseWithMessage;
import com.mailgun.model.domains.DomainCredentials;

// ...

public ResponseWithMessage createCredentials() {
    MailgunDomainsApi mailgunDomainsApi = MailgunClient.config(API_KEY)
        .createApi(MailgunDomainsApi.class);

    DomainCredentials domainCredentials = DomainCredentials.builder()
        .login("alice@YOUR_DOMAIN_NAME.com")
        .password( "super_secret_password")
        .build();

    return mailgunDomainsApi.createNewCredentials(YOUR_DOMAIN_NAME, domainCredentials);
}

{
  "message": "Created 1 credentials pair(s)"
}

Updating the password for a given credential:

import com.mailgun.api.v3.MailgunDomainsApi;
import com.mailgun.model.ResponseWithMessage;

// ...

public ResponseWithMessage updatePassword() {
    MailgunDomainsApi mailgunDomainsApi = MailgunClient.config(API_KEY)
        .createApi(MailgunDomainsApi.class);

    return mailgunDomainsApi.updateCredentials(YOUR_DOMAIN_NAME, YOUR_LOGIN, "super_secret_password");
}

Sample Response

{
  "message": "Password changed"
}

Deleting a given credential:

import com.mailgun.api.v3.MailgunDomainsApi; import com.mailgun.model.ResponseWithMessage;

// …

public ResponseWithMessage deleteCredentials() {
MailgunDomainsApi mailgunDomainsApi = MailgunClient.config(API_KEY)
.createApi(MailgunDomainsApi.class);
return mailgunDomainsApi.deleteCredentials(YOUR_DOMAIN_NAME, YOUR_LOGIN);

Sample Response:

{
  "message": "Credentials have been deleted",
  "spec": "alice@samples.mailgun.org"
}

Spam Filter

A spam filter is necessary when receiving email. Mailgun is powered by an army of SpamAssassin machines. Mailgun gives you three ways to configure spam filtering.

Click the Domains tab on the Control Panel and select from one of the following three options:

• Disabled (default)
• Delete Spam (spam is removed and you won't see it)
• Mark spam with MIME headers (You decide what to do with it)

If you choose to mark spam with MIME headers, Mailgun provides you with these four:

• X-Mailgun-Sflag - Inserted with the value Yes if the message was classified as spam.
• X-Mailgun-Sscore - A 'spamicity' score that you can use to calibrate your own filter. Inserted for every message checked for spam. The score ranges from low negative digits (very unlikely to be spam) to 20 and occasionally higher (very likely to be spam).
• X-Mailgun-Dkim-Check-Result - If DKIM is used to sign an inbound message, Mailgun will attempt DKIM validation, the results will be stored in this header. Possible values are: Pass or Fail
• X-Mailgun-Spf -Mailgun will perform an SPF validation, and results will be stored in this header. Possible values are: Pass , Neutral , Fail or SoftFail .