GreenArrow Email Software Documentation

Routes API

GreenArrow CloudMTA

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


id

integer

/

read-only

A unique automatically generated identifier.

name

string

/

required

A descriptive name for this route.

  • Must be present and no longer than 180 characters.
  • Must be unique (case insensitive) among non-deleted routes.
  • May contain letters, numbers, spaces, hyphens, underscores, and periods.
  • Must not be a plain integer.
description

string

/

optional

A description of this route. It is stored exactly as sent, with no whitespace removed.

  • No longer than 10,240 characters. The limit counts characters, not bytes.
  • "" when the route has no description. null is stored as "", so this field is never null.
ips

array of strings

/

read-only

The IP addresses that send the route’s email. GreenArrow assigns these IP addresses automatically.

  • Each address is in its normal text form, and occurs once.
  • Addresses are in numeric order, with IPv4 addresses before IPv6 addresses.
  • [] when the route has no addresses.
is_used_by_sending_domains

boolean

/

read-only

true when the route of a Sending Domain is this route. Sending Domains with sending_enabled or dns_verified set to false also count. Deleted Sending Domains do not count. Other ways to send through the route, for example a Mail Class or an X-GreenArrow-Route header, do not count.

requested_target_daily_volume

integer

/

optional

The daily volume that this route expects to send, as requested by the user. This is used to determine how many IP addresses to assign to the route.

recommended_max_daily_volume

integer

/

read-only

The maximum recommended daily volume to send through the route, to avoid overflow or delay of email.1

recommended_max_delivery_rate_per_hour

integer

/

read-only

The maximum recommended messages per hour to send through the route, to avoid overflow or delay of email.1

routing_rule

hash

/

read-only



The Routing Rule that is automatically created and managed for this route.

id

integer

The unique identifier of the routing rule.

name

string

The name of the routing rule.

  1. 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 give not_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 0.

page_token

string

/

optional

The page_token to retrieve the next page based on the prior query results.

A page_token keeps the order_by of the request that returned it. So if you start with no page_token and follow next_page_token until it is null, you get each route once, in one order.

Send the same filters (name) with each page_token. In name order, if the last route of the prior page is deleted, or no longer matches your filters, before you request the next page, the request fails with the error code invalid_request and the message “the next record has been deleted, please restart your request”. Start again from the first page. If that route is renamed, the next pages can skip or repeat routes.

order_by

string

/

optional

The order of the routes: name or id. name orders the routes by name, ignoring letter case. Another value fails with the error code invalid_request.

Defaults to name.

name

string

/

optional

Filter routes by name. This performs a case-insensitive substring match, so name=alpha would match routes named “alpha-route”, “Alpha Route”, etc.

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


page

integer

The page number of this result set. Page numbers start at 0.

per_page

integer

The number of records returned on each page.

num_pages

integer

The total number of pages in the result set.

num_records

integer

The total number of records that are in the result set.

next_page_token

string

A unique identifier that can be used to retrieve the next result set.

null is returned if this is the last page.

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_route_id

integer

/

optional

The id of the route that replaces the deleted route. It must be a route that is not deleted, and not the route that is being deleted. The Sending Domains that use the deleted route move to this route, and email that is already queued for the deleted route is delivered through this route. Deleted Sending Domains do not move.

A route that a Sending Domain uses cannot be deleted without this parameter. A Sending Domain with sending_enabled or dns_verified set to false also counts. A deleted Sending Domain does not.

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
}


Copyright © 2012–2026 GreenArrow Email