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
priority
integer

Smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.

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
object
Request samples
multipart/form-data
{
  "priority": 0,
  "description": "it's a new route",
  "expression": "match_recipient('.*@gmail.com')",
  "action": [
    "forward(\"http://myhost.com/messages/\")"
  ]
}
Response samples
application/json
{
  • "message": "Route has been created",
  • "route": {
    • "id": "4f3bad2335335426750048c6",
    • "priority": 0,
    • "description": "it's a new route",
    • "expression": "match_recipient('.*@gmail.com')",
    • "actions": [
      ],
    • "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
Array of objects
400

Bad Request

Request samples 
Response samples 
application/json
{
  • "total_count": 1,
  • "items": [
    • {
      }
    ]
}
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
 
priority
integer
 
description
string
 
expression
string
 
actions
Array of strings
 
created_at
string
 
404
Not Found


Request samples 
Response samples 
application/json
{
  • "route": {
    • "id": "4f3bad2335335426750048c6",
    • "priority": 0,
    • "description": "Sample route",
    • "expression": "match_recipient(\".*@samples.mailgun.org\")",
    • "actions": [
      ],
    • "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
 
object
 
404
Not Found


Request samples 
multipart/form-data
{
  "id": "4f3bad2335335426750048c6",
  "priority": 0,
  "description": "Sample route",
  "expression": "match_recipient(\".*@samples.mailgun.org\")",
  "action": [
    "forward(\"http://myhost.com/messages/\")",
    "stop()"
  ]
}
Response samples 
application/json
{
  • "message": "Route has been updated",
  • "route": {
    • "id": "4f3bad2335335426750048c6",
    • "priority": 0,
    • "description": "Sample route",
    • "expression": "match_recipient(\".*@samples.mailgun.org\")",
    • "actions": [
      ],
    • "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
 
id
string
 
404
Not Found


Request samples 
Response samples 
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
string
address to match routes on


 
Responses 
200
OK


Response Schema: application/json
object
 
id
string
 
priority
integer
 
description
string
 
expression
string
 
actions
Array of strings
 
created_at
string
 
404
Not Found


Request samples 
Response samples 
application/json
{
  • "route": {
    • "id": "4f3bad2335335426750048c6",
    • "priority": 0,
    • "description": "Sample route",
    • "expression": "match_recipient(\".*@samples.mailgun.org\")",
    • "actions": [
      ],
    • "created_at": "Wed, 15 Feb 2012 13:03:31 GMT"
    }
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.