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:

curl -s --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()'

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);
}

function create_route() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v2/routes');
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch,
              CURLOPT_POSTFIELDS,
              array('priority' => 1,
                    'expression' => 'match_recipient(".*@samples.mailgun.org")',
                    'action[1]' => 'forward("http://host.com/messages")',
                    'action[2]' => 'stop()',
                    'description' => 'Sample route'));

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}

def create_route():
    return 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()")]))

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

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);
}

Sample response:

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

Listing routes:

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

public static ClientResponse GetRoutes() {
       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);
}

function get_routes() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v2/routes?skip=1&limit=1');

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}

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

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

public static RestResponse GetRoutes() {
       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);
}

Sample response:

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

Access the route by id:

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

public static ClientResponse GetRoute() {
       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);
}

function get_route() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v2/routes/4e97c1b2ba8a48567f007fb6');

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}

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

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

public static RestResponse GetRoute() {
       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);
}

Sample response:

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