Routes API
- Table of Contents
- Overview
- Attributes
- Error Codes
- Get a List of Routes
- Get a Single Route
- Create a Route
- Update a Route
- Delete a Route
This feature is only available on GreenArrow CloudMTA.
Overview
Routes provide a way to manage groups of IP addresses and their associated routing rules for email delivery. When a Route is created, it automatically provisions IP addresses from GreenArrow Cloud and creates a Routing Rule that directs mail through those IPs.
Software that was written for Mailgun’s dedicated IP pool API can read and create Routes as IP pools through the Mailgun-Compatible IP Pool API.
Attributes
The following are the configurable attributes defined for Routes.
|
route
hash /required
|
|||||||||||||||||||||||
- The recommended daily volume and delivery rate fields are totals across all recipient domains and assume a normal blend of recipient domains. This means that if you send an entire daily volume of emails to a single recipient domain or a larger than normal percentage to a particular recipient domain, then the Route will overflow before these limits are reached. This is because the underlying mechanics of the limits are per-recipient domain.
Error Codes
Every Routes API call can return the following error, in addition to the standard API error responses.
-
feature_not_enabled: Routes are not enabled on this GreenArrow installation. Missing or invalid credentials givenot_authorized, also when Routes are not enabled.
{
"success": false,
"data": null,
"error_code": "feature_not_enabled",
"error_messages": [
"Routes are not enabled on this GreenArrow installation"
]
}
A create or a delete can also return the following errors. They mean that GreenArrow could not set up the route’s IP addresses and Routing Rule (create), or could not remove them (delete). The request itself was valid. A create that fails makes no route. A delete that fails does not delete the route, and the route normally keeps its IP addresses.
-
provisioning_capacity_exhausted(create only): GreenArrow Cloud has no IP addresses available for a new route. Try again later, or contact GreenArrow support. -
provisioning_failed: another failure stopped GreenArrow from setting up or removing the route’s IP addresses or Routing Rule. Contact GreenArrow support.
A route that is not valid (for example, a name that another route has) gives validation_failed, as in the other
Engine APIs.
{
"success": false,
"data": null,
"error_code": "provisioning_capacity_exhausted",
"error_messages": [
"CRM request_ip_addresses failed: there are an insufficient number of ip addresses available for this allocation"
]
}
A delete can also return replacement_route_required or replacement_route_invalid. See
Delete a Route.
Get a List of Routes
GET /ga/api/v3/eng/routes
Parameters
The following parameters are valid for the above endpoint.
|
page
integer /optional |
The page number from which to retrieve. Page numbering starts at |
|
page_ string /optional |
The A Send the same filters ( |
|
order_ string /optional |
The order of the routes: Defaults to |
|
name
string /optional |
Filter routes by name. This performs a case-insensitive substring match, so |
Response
The response will contain a list of Routes in the following format.
|
routes
array of hashes |
Each hash contains all of the attributes listed in the Attributes section. |
||||||||||
|
pagination
hash
|
|||||||||||
Example
GET /ga/api/v3/eng/routes
HTTP/1.1 200 OK
{
"routes": [
{
"id": 1,
"name": "my-route",
"description": "Transactional mail",
"ips": ["192.0.2.9", "192.0.2.10"],
"is_used_by_sending_domains": true,
"requested_target_daily_volume": 50000,
"recommended_max_daily_volume": 25000,
"recommended_max_delivery_rate_per_hour": 10000,
"routing_rule": {
"id": 42,
"name": "my-route R1"
}
}
],
"pagination": {
"page": 0,
"per_page": 100,
"num_pages": 1,
"num_records": 1,
"next_page_token": null
}
}
Get a Single Route
GET /ga/api/v3/eng/routes/{id}
Example
GET /ga/api/v3/eng/routes/1
HTTP/1.1 200 OK
{
"route": {
"id": 1,
"name": "my-route",
"description": "Transactional mail",
"ips": ["192.0.2.9", "192.0.2.10"],
"is_used_by_sending_domains": true,
"requested_target_daily_volume": 50000,
"recommended_max_daily_volume": 25000,
"recommended_max_delivery_rate_per_hour": 10000,
"routing_rule": {
"id": 42,
"name": "my-route R1"
}
}
}
Create a Route
POST /ga/api/v3/eng/routes
Parameters
See the Attributes section for valid parameters.
If GreenArrow cannot set up the route’s IP addresses and Routing Rule, the create fails with
provisioning_capacity_exhausted or provisioning_failed. See Error Codes.
Example
POST /ga/api/v3/eng/routes
{
"route": {
"name": "new-route",
"description": "Receipts and account notices",
"requested_target_daily_volume": 50000
}
}
HTTP/1.1 200 OK
{
"route": {
"id": 2,
"name": "new-route",
"description": "Receipts and account notices",
"ips": ["192.0.2.11"],
"is_used_by_sending_domains": false,
"requested_target_daily_volume": 50000,
"recommended_max_daily_volume": 25000,
"recommended_max_delivery_rate_per_hour": 10000,
"routing_rule": {
"id": 43,
"name": "new-route R2"
}
}
}
Update a Route
PUT /ga/api/v3/eng/routes/{id}
Parameters
See the Attributes section for valid parameters.
Example
PUT /ga/api/v3/eng/routes/1
{
"route": {
"name": "renamed-route",
"description": "",
"requested_target_daily_volume": 75000
}
}
HTTP/1.1 200 OK
{
"route": {
"id": 1,
"name": "renamed-route",
"description": "",
"ips": ["192.0.2.9", "192.0.2.10"],
"is_used_by_sending_domains": true,
"requested_target_daily_volume": 75000,
"recommended_max_daily_volume": 25000,
"recommended_max_delivery_rate_per_hour": 10000,
"routing_rule": {
"id": 42,
"name": "renamed-route R1"
}
}
}
Delete a Route
Deleting a Route performs the following actions:
- With
replacement_route_id, moves the Sending Domains that use the route to the replacement route. - Redirects the Routing Rule to send all email to the Routing Rule of the replacement route, or, with no replacement, to the “dump from queue” relay server. Email that is already queued for the deleted route is then delivered through the replacement route, or discarded.
- Removes the IP addresses for that route from GreenArrow.
DELETE /ga/api/v3/eng/routes/{id}
Parameters
The following parameters are valid for the above endpoint.
|
replacement_ integer /optional |
The A route that a Sending Domain uses cannot be deleted without this parameter. A Sending Domain with
|
A delete without replacement_route_id of a route that a Sending Domain uses fails with
replacement_route_required. The message names up to 20 of the Sending Domains.
{
"success": false,
"data": null,
"error_code": "replacement_route_required",
"error_messages": [
"The following Sending Domains depend on this record: mail.example.com"
]
}
A replacement_route_id that is not an integer, that is the route being deleted, that is not the id of a route that
is not deleted, or that names a route with no Routing Rule, fails with replacement_route_invalid.
{
"success": false,
"data": null,
"error_code": "replacement_route_invalid",
"error_messages": [
"replacement_route_id must be the id of a route that is not deleted"
]
}
If GreenArrow cannot release the route’s IP addresses or do these actions, the delete fails with
provisioning_failed, and the route is not deleted. The Sending Domains do not move, and the route normally keeps its
IP addresses. See Error Codes.
If GreenArrow Cloud does not confirm that it took back the route’s IP addresses, for example because its response was lost, the delete succeeds, so that the route stops sending from addresses that GreenArrow Cloud can give to another customer. GreenArrow support then checks the addresses.
Example
DELETE /ga/api/v3/eng/routes/1
HTTP/1.1 200 OK
{
"success": true
}
Delete route 1. Its Sending Domains move to route 2, and email that is already queued for route 1 is delivered through route 2:
DELETE /ga/api/v3/eng/routes/1?replacement_route_id=2
HTTP/1.1 200 OK
{
"success": true
}
