Routes

Mailgun Routes are a powerful way to handle the incoming traffic. See Routes section in the User Manual to learn more about how they work.

This API allows you to work with routes programmatically. Mailgun Control Panel itself uses this API.

GET /routes

Fetches the list of routes. Note that routes are defined globally, per account, not per domain as most of other API calls.

Parameter	Description
limit	Maximum number of records to return. (100 by default)
skip	Number of records to skip. (0 by default)

GET /routes/<id>

Returns a single route object based on its ID. See examples below.

POST /routes

Creates a new route.

Parameter	Description
priority	Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.
description	An arbitrary string.
expression	A filter expression like match_recipient('.*@gmail.com')
action:	Route action. This action is executed when the expression evaluates to True. Example: forward("alex@mailgun.net") You can pass multiple action parameters.

PUT /routes/<id>

Updates a given route by ID. All parameters are optional: this API call only updates the specified fields leaving others unchanged.

Parameter	Description
priority	Integer: smaller number indicates higher priority. Higher priority routes are handled first.
description	An arbitrary string.
expression	A filter expression like match_recipient('.*@gmail.com')
action:	Route action. This action is executed when the expression evaluates to True. Example: forward("alex@mailgun.net") You can pass multiple action parameters.

DELETE /routes/<id>

Deletes a route based on the id.

Examples

Create a route of the highest priority with multiple actions:

def create_route
  data = Multimap.new
  data[:priority] = 1
  data[:description] = "Sample route"
  data[:expression] = "match_recipient('.*@samples.mailgun.org')"
  data[:action] = "forward('http://myhost.com/messages/')"
  data[:action] = "stop()"
  RestClient.post "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/routes", data
end

Response:

{
  "message": "Route has been created",
  "route": {
    "description": "Sample route",
    "created_at": "Fri, 03 Feb 2012 17:07:22 GMT",
    "actions": [
      "forward('http://myhost.com/messages/')",
      "stop()"
    ],
    "priority": 1,
    "expression": "match_recipient('.*@samples.mailgun.org')",
    "id": "4f2c144a3181336846057b77"
  }
}

Listing routes:

def list_routes
  RestClient.get "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/routes", :params => {
    :skip => 1,
    :limit => 1
  }
end

Response:

{
  "total_count": 167,
  "items": [
    {
      "description": "Sample route",
      "created_at": "Fri, 03 Feb 2012 17:07:21 GMT",
      "actions": [
        "forward('http://myhost.com/messages/')",
        "stop()"
      ],
      "priority": 1,
      "expression": "match_recipient('.*@samples.mailgun.org')",
      "id": "4f2c14493181336846057b6d"
    }
  ]
}

Access the route by id:

def access_route_by_id
  RestClient.
    get("https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
        "@api.mailgun.net/v2/routes/"\
        "4e97c1b2ba8a48567f007fb6"){|response, request, result| response }
end

Response:

{
  "message": "Route not found"
}

Create a route of the highest priority with multiple actions:

public static ClientResponse CreateRoute() {
       Client client = Client.create();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/routes");
       MultivaluedMapImpl formData = new MultivaluedMapImpl();
       formData.add("priority", 1);
       formData.add("description", "Sample route");
       formData.add("expression", "match_recipient('.*@samples.mailgun.org')");
       formData.add("action", "forward('http://myhost.com/messages/')");
       formData.add("action", "stop()");
       return webResource.type(MediaType.APPLICATION_FORM_URLENCODED).
               post(ClientResponse.class, formData);

}

Response:

{
  "message": "Route has been created",
  "route": {
    "description": "Sample route",
    "created_at": "Wed, 23 Nov 2011 09:37:56 GMT",
    "actions": [
      "forward(r'http://myhost.com/messages/')",
      "stop()"
    ],
    "priority": 1,
    "expression": "match_recipient(r'.*@samples.mailgun.org')",
    "id": "4eccbef4ba8a4857aa00f35b"
  }
}

Listing routes:

public static ClientResponse ListRoutes() {
       Client client = Client.create();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/routes");
       MultivaluedMapImpl queryParams = new MultivaluedMapImpl();
       queryParams.add("skip", 1);
       queryParams.add("limit", 1);
       return webResource.queryParams(queryParams).get(ClientResponse.class);
}

Response:

{
  "total_count": 33,
  "items": [
    {
      "description": "Sample route",
      "created_at": "Wed, 23 Nov 2011 09:37:41 GMT",
      "actions": [
        "forward(r'http://myhost.com/messages/')",
        "stop()"
      ],
      "priority": 1,
      "expression": "match_recipient(r'.*@samples.mailgun.org')",
      "id": "4eccbee51476d8676900f270"
    }
  ]
}

Access the route by id:

public static ClientResponse AccessRouteById() {
       Client client = Client.create();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/routes" +
                               "/4e97c1b2ba8a48567f007fb6");
       return webResource.get(ClientResponse.class);
}

Response:

{
  "message": "Route not found"
}

Create a route of the highest priority with multiple actions:

function create_route() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/routes',
                    HttpRequest::METH_POST);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $data = array(
                'priority' => 1,
                'description' => 'Sample route',
                'expression' => 'match_recipient(".*@samples.mailgun.org")',
                'action' => array('forward("http://myhost.com/messages/")',
                                  'action' => 'stop()')
                );
  $dataString = '';
  foreach ($data as $key => $val) {
    if (is_array($val)) {
      foreach ($val as $v) {
        $dataString .= urlencode($key).'='.urlencode($v).'&';
      }
    } else {
      $dataString .= urlencode($key).'='.urlencode($val).'&';
    }
  }
  $request->setRawPostData(substr($dataString, 0, -1));
  $request->send();
  return $request;
}

Response:

{
  "message": "Route has been created",
  "route": {
    "description": "Sample route",
    "created_at": "Wed, 23 Nov 2011 09:37:04 GMT",
    "actions": [
      "forward(\"http://myhost.com/messages/\")",
      "stop()"
    ],
    "priority": 1,
    "expression": "match_recipient(\".*@samples.mailgun.org\")",
    "id": "4eccbec0ba8a4857ab00ef3d"
  }
}

Listing routes:

function list_routes() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/routes',
                    HttpRequest::METH_GET);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->setQueryData(array('skip' => 1, 'limit' => 1));
  $request->send();
  return $request;
}

Response:

{
  "total_count": 30,
  "items": [
    {
      "description": "Sample route",
      "created_at": "Wed, 23 Nov 2011 09:36:51 GMT",
      "actions": [
        "forward('http://myhost.com/messages/')",
        "stop()"
      ],
      "priority": 1,
      "expression": "match_recipient('.*@samples.mailgun.org')",
      "id": "4eccbeb3ba8a4857ab00ef31"
    }
  ]
}

Access the route by id:

function access_route_by_id() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/routes/'.
                    '4e97c1b2ba8a48567f007fb6',
                    HttpRequest::METH_GET);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->send();
  return $request;
}

Response:

{
  "message": "Route not found"
}

Create a route of the highest priority with multiple actions:

def create_route():
    r = requests.\
        post("https://api.mailgun.net/v2/routes",
             auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
             data=MultiDict([
                 ("priority", 1),
                 ("description", "Sample route"),
                 ("expression",
                  "match_recipient('.*@samples.mailgun.org')"),
                 ("action",
                  "forward('http://myhost.com/messages/')"),
                 ("action", "stop()")
                 ]))
    return r

Response:

{
  "message": "Route has been created",
  "route": {
    "description": "Sample route",
    "created_at": "Tue, 07 Feb 2012 07:15:19 GMT",
    "actions": [
      "forward('http://myhost.com/messages/')",
      "stop()"
    ],
    "priority": 1,
    "expression": "match_recipient('.*@samples.mailgun.org')",
    "id": "4f30cf87947a8d7bf50245d9"
  }
}

Listing routes:

def list_routes():
    r = requests.\
        get("https://api.mailgun.net/v2/routes",
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
            params={
                "skip": 1,
                "limit": 1
                }
            )
    return r

Response:

{
  "total_count": 207,
  "items": [
    {
      "description": "Sample route",
      "created_at": "Tue, 07 Feb 2012 07:15:18 GMT",
      "actions": [
        "forward('http://myhost.com/messages/')",
        "stop()"
      ],
      "priority": 1,
      "expression": "match_recipient('.*@samples.mailgun.org')",
      "id": "4f30cf8631813367e902475e"
    }
  ]
}

Access the route by id:

def access_route_by_id():
    r = requests.\
        get(("https://api.mailgun.net/v2/routes/"
             "4e97c1b2ba8a48567f007fb6"),
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"))
    return r

Response:

{
  "message": "Route not found"
}

Create a route of the highest priority with multiple actions:

public static RestResponse CreateRoute() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.Resource = "routes";
       request.AddParameter("priority", 1);
       request.AddParameter("description", "Sample route");
       request.AddParameter("expression",
                            "match_recipient('.*@samples.mailgun.org')");
       request.AddParameter("action",
                            "forward('http://myhost.com/messages/')");
       request.AddParameter("action", "stop()");
       request.Method = Method.POST;
       return client.Execute(request);
}

Response:

{
  "message": "Route has been created",
  "route": {
    "description": "Sample route",
    "created_at": "Wed, 23 Nov 2011 09:38:11 GMT",
    "actions": [
      "forward('http://myhost.com/messages/')",
      "stop()"
    ],
    "priority": 1,
    "expression": "match_recipient('.*@samples.mailgun.org')",
    "id": "4eccbf031476d8676800f003"
  }
}

Listing routes:

public static RestResponse ListRoutes() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.Resource = "routes";
       request.AddParameter("skip", 1);
       request.AddParameter("limit", 1);
       return client.Execute(request);
}

Response:

{
  "total_count": 34,
  "items": [
    {
      "description": "Sample route",
      "created_at": "Wed, 23 Nov 2011 09:37:56 GMT",
      "actions": [
        "forward(r'http://myhost.com/messages/')",
        "stop()"
      ],
      "priority": 1,
      "expression": "match_recipient(r'.*@samples.mailgun.org')",
      "id": "4eccbef4ba8a4857aa00f35b"
    }
  ]
}

Access the route by id:

public static RestResponse AccessRouteById() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.Resource = "routes/{id}";
       request.AddUrlSegment("id", "4e97c1b2ba8a48567f007fb6");
       return client.Execute(request);
}

Response:

{
  "message": "Route not found"
}

Create a route of the highest priority with multiple actions:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 \
    https://api.mailgun.net/v2/routes \
    -F priority=1 \
    -F description='Sample route' \
    -F expression='match_recipient(".*@samples.mailgun.org")' \
    -F action='forward("http://myhost.com/messages/")'\
    -F action='stop()'

Response:

{
  "message": "Route has been created",
  "route": {
      "description": "Sample route",
      "created_at": "Wed, 15 Feb 2012 12:52:20 GMT",
      "actions": [
          "forward(\"http://myhost.com/messages/\")",
          "stop()"
      ],
      "priority": 1,
      "expression": "match_recipient(\".*@samples.mailgun.org\")",
      "id": "4f3baa84ba8a481c64004225"
  }
}

Listing routes:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 -G \
    https://api.mailgun.net/v2/routes \
    -d skip=1 \
    -d limit=1

Response:

{
  "total_count": 260,
  "items": [
      {
          "description": "Sample route",
          "created_at": "Wed, 15 Feb 2012 12:35:59 GMT",
          "actions": [
              "forward(\"http://myhost.com/messages/\")",
              "stop()"
          ],
          "priority": 1,
          "expression": "match_recipient(\".*@samples.mailgun.org\")",
          "id": "4f3ba6af31813312ce002ddc"
      }
  ]
}

Access the route by id:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 \
    https://api.mailgun.net/v2/routes/4f3baa84ba8a481c64004225

Response:

{
  "route": {
      "description": "Sample route",
      "created_at": "Wed, 15 Feb 2012 12:52:20 GMT",
      "actions": [
          "forward(\"http://myhost.com/messages/\")",
          "stop()"
      ],
      "priority": 1,
      "expression": "match_recipient(\".*@samples.mailgun.org\")",
      "id": "4f3baa84ba8a481c64004225"
  }
}