Routes API

Table of Contents
Overview
Attributes
Get a List of Routes
Get a Single Route
Create a Route
Update a Route
Delete a Route

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.

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.

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.

overflow_route
hash
/
optional

The route that will be used for sending email that this route’s IP addresses cannot accept due to volume and speed limits.

id integer	The unique identifier of the overflow route.
name string	The unique name of the overflow 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.¹

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.¹

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.

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 the underlying mechanics of the limits are per-recipient domain.

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.
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",
      "requested_target_daily_volume": 50000,
      "recommended_max_daily_volume": 25000,
      "recommended_max_delivery_rate_per_hour": 10000,
      "overflow_route": null,
      "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",
    "requested_target_daily_volume": 50000,
    "recommended_max_daily_volume": 25000,
    "recommended_max_delivery_rate_per_hour": 10000,
    "overflow_route": null,
    "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.

Example

POST /ga/api/v3/eng/routes

{
  "route": {
    "name": "new-route",
    "requested_target_daily_volume": 50000
  }
}

HTTP/1.1 200 OK

{
  "route": {
    "id": 2,
    "name": "new-route",
    "requested_target_daily_volume": 50000,
    "recommended_max_daily_volume": 25000,
    "recommended_max_delivery_rate_per_hour": 10000,
    "overflow_route": null,
    "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",
    "requested_target_daily_volume": 75000
  }
}

HTTP/1.1 200 OK

{
  "route": {
    "id": 1,
    "name": "renamed-route",
    "requested_target_daily_volume": 75000,
    "recommended_max_daily_volume": 25000,
    "recommended_max_delivery_rate_per_hour": 10000,
    "overflow_route": null,
    "routing_rule": {
      "id": 42,
      "name": "renamed-route R1"
    }
  }
}

Delete a Route

Deleting a Route performs the following actions:

Redirects the Routing Rule to send all email to the “dump from queue” relay server.
Removes the IP addresses for that route from GreenArrow.

DELETE /ga/api/v3/eng/routes/{id}

Example

DELETE /ga/api/v3/eng/routes/1

HTTP/1.1 200 OK

{
  "success": true
}