Routes

Define a list of routes to handle incoming emails. When a message matches a route expression, Mailgun can forward it on to your application via HTTP or another email address, or store the message temporarily (3 days) for subsequent retrieval.

Create a route

post/v3/routes

Adds a new route to the account

SecuritybasicAuth

Request

Request Body schema: multipart/form-data

expression required	string The filtering rule.
priority	integer Smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.
description	string An arbitrary string.
action	Array of strings This action is executed when the expression evaluates to True. You can pass multiple parameters.

Responses

200

OK

Response Schema: application/json

message	string A string describing the result of the operation
	object The created route

Request samples

multipart/form-data

{
  "priority": 0,
  "description": "it's a new route",
  "expression": "match_recipient('.*@gmail.com')",
  "action": [
    "forward(\"http://myhost.com/messages/\")",
    "stop()"
  ]
}

Response samples

200

application/json

{"message": "Route has been created",
"route": {"id": "4f3bad2335335426750048c6",
"priority": 0,
"description": "it's a new route",
"expression": "match_recipient('.*@gmail.com')",
"actions": ["forward(\"http://myhost.com/messages/\")"
],
"created_at": "Wed, 15 Feb 2012 13:03:31 GMT"
}
}

Get all routes

get/v3/routes

Get the list of routes. Note that routes are defined globally, per account, not per domain.

SecuritybasicAuth

Request

query Parameters

skip	string Number of records to skip. Defaults to 0.
limit	string Maximum number of records to return. Defaults to 100.

Responses

200

OK

Response Schema: application/json

total_count	integer Total number of routes in the account
	Array of objects List of routes

400

Bad Request

Request samples

Response samples

200
400

application/json

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

Get a route

get/v3/routes/{id}

Returns a detailed view of the route

SecuritybasicAuth

Request

path Parameters

id

required

string

The unique identifier of the route

Responses

200

OK

Response Schema: application/json

object

id	string Unique identifier of the route
priority	integer Smaller number indicates higher priority. Higher priority routes are handled first.
description	string An arbitrary string.
expression	string The filtering rule.
actions	Array of strings These actions are executed when the expression evaluates to True.
created_at	string Timestamp indicating when the route was created in RFC1123 format

404

Not Found

Request samples

Response samples

200
404

application/json

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

Update a route

put/v3/routes/{id}

Updates a given route. All parameters are optional. This only updates the specified fields, leaving others unchanged.

SecuritybasicAuth

Request

path Parameters

id

required

string

ID of the route

Request Body schema: multipart/form-data

id	string Unique identifier of the route
priority	integer Smaller number indicates higher priority. Higher priority routes are handled first.
description	string An arbitrary string.
expression	string The filtering rule.
action	Array of strings This action is executed when the expression evaluates to True. You can pass multiple parameters.

Responses

200

OK

Response Schema: application/json

message	string A string describing the result of the operation
	object

404

Not Found

Request samples

multipart/form-data

{
  "priority": 0,
  "description": "Sample route",
  "expression": "match_recipient(\".*@samples.mailgun.org\")",
  "action": [
    "forward(\"http://myhost.com/messages/\")",
    "stop()"
  ]
}

Response samples

200
404

application/json

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

Delete a route

delete/v3/routes/{id}

Remove the rotue from the account.

SecuritybasicAuth

Request

path Parameters

id

required

string

ID of the route

Responses

200

OK

Response Schema: application/json

message	string A string describing the result of the operation
id	string ID of the deleted route

404

Not Found

Request samples

Response samples

200
404

application/json

{"message": "Route has been deleted",
"id": "4f3bad2335335426750048c6"
}

Match address to route

get/v3/routes/match

Checks if an address matches at least one route.

SecuritybasicAuth

Request

query Parameters

address

required

string

address to match routes on

Responses

200

OK

Response Schema: application/json

object

id	string Unique identifier of the route
priority	integer Smaller number indicates higher priority. Higher priority routes are handled first.
description	string An arbitrary string.
expression	string The filtering rule.
actions	Array of strings These actions are executed when the expression evaluates to True.
created_at	string Timestamp indicating when the route was created in RFC1123 format

404

Not Found

Request samples

Response samples

200
404

application/json

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