Routing Rules API

Table of Contents
Overview
Attributes
Routing Rules
Domain Overrides

Overview

Routing Rules contain a default list of VirtualMTAs through which to deliver. It also contains a list of Domain Overrides which will supersede those defaults on a per-domain basis.

Attributes

routing_rule
hash
/
required

id
integer
/
read-only

An automatically generated identifier.

name
string
/
required

A descriptive name to associate with this Routing Rule.

Must contain only ASCII characters in the range 0x20-0x7e; excluding comma, pound, and at-sign.
Must not have leading nor trailing whitespace.
Must be unique (case-insensitive) across all types of VirtualMTAs (IP Addresses, Relay Servers, and Routing Rules).
Must not also be an integer.
Must be from 1 to 200 characters in length.

domain_overrides
array of hashes

Each entry in the domain_overrides array contains a list of domains to which it applies and a list of VirtualMTAs through which to deliver.

id
integer
/
read-only

Unique identifier for this rule entry.

domains
array of strings

The list of domains to which this rule applies.

If a domain is prefixed with [*.], it will apply to itself and any subdomain. For example, [*.]web.example.com will match web.example.com, second.web.example.com, and third.second.web.example.com.

If a domain is prefixed with *., it will apply to any subdomain, but not itself. For example, *.web.example.com will match second.web.example.com and third.second.web.example.com but not web.example.com.

Must be valid domain names
Must contain at least one domain name
Each domain must be unique (case-insensitive) across all rules in this Routing Rule

randomization_type
string
/
required

Define the level on which to randomize messages.

Fully Random (random) - Each delivery attempt gets a random VirtualMTA.
Message Constant (message_constant) - Each delivery attempt for the same message goes on the same VirtualMTA. However, different messages to the same email address may go out on different VirtualMTAs.
Email Address Constant (email_address_constant) - Each delivery attempt for the same email address, regardless of the message, always goes on the same VirtualMTA.

May be: random, message_constant, or email_address_constant

deliver_through
array of hashes

Each entry in the deliver_through array contains a single destination VirtualMTA.

Limit on the number of destinations: We do not recommend adding or editing more than 2,500 destinations via the API. See the configuration file for up to 10,000 destinations. While GreenArrow does not enforce a hard limit on the number of destinations, performance can suffer when exceeding these thresholds.

virtual_mta
hash

id integer	The identifier of the VirtualMTA for delivery.
name string	The case-insensitive `name` of the VirtualMTA for delivery. If both `id` and `name` are present when creating or updating a Routing Rule, the value in `name` is ignored.

portion_of_mail
float

The portion of email that should be delivered to this VirtualMTA. If the sum of portion_of_email across all VirtualMTAs in this rule does not total 100, each value is proportionally scaled so they total 100 (as closely as possible given one digit after the decimal point) when the record is saved.

Must be a positive number
Only one decimal point of precision is stored

default
hash
/
required

randomization_type
string
/
required

Define the level on which to randomize messages.

Fully Random (random) - Each delivery attempt gets a random VirtualMTA.
Message Constant (message_constant) - Each delivery attempt for the same message goes on the same VirtualMTA. However, different messages to the same email address may go out on different VirtualMTAs.
Email Address Constant (email_address_constant) - Each delivery attempt for the same email address, regardless of the message, always goes on the same VirtualMTA.

May be: random, message_constant, or email_address_constant

deliver_through
array of hashes

Each entry in the deliver_through array contains a single destination VirtualMTA.

virtual_mta
hash

id integer	The identifier of the VirtualMTA for delivery.
name string	The case-insensitive `name` of the VirtualMTA for delivery. If both `id` and `name` are present when creating or updating a Routing Rule, the value in `name` is ignored.

portion_of_mail
float

The portion of email that should be delivered to this VirtualMTA. If the sum of portion_of_email across all VirtualMTAs in this rule does not total 100, they are proportionally scaled to total 100.

Must be a positive number
Only one decimal point of precision is stored

Routing Rules

Get a List of Routing Rules

GET /ga/api/v3/eng/routing_rules
GET /ga/api/v3/eng/routing_rules?page={page}
GET /ga/api/v3/eng/routing_rules?page_token={page_token}

Parameters

page integer / optional	The page number to retrieve. Page numbering starts at `0`.
page_token string / optional	The `page_token` can be used to retrieve the next page of results.

Response

routing_rules
array of hashes

id integer	Automatically generated identifier.
name string	User supplied identifier.

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/routing_rules

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "routing_rules": [
      {
        "id": 6,
        "name": "rr-1"
      },
      {
        "id": 9,
        "name": "rr-2"
      },
      {
        "id": 11,
        "name": "rr-3"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get all Details About a single Routing Rule

GET /ga/api/v3/eng/routing_rules/{id}

Response

routing_rule
hash

The attributes for this hash are defined in the Attributes section of this document.

Example

GET /ga/api/v3/eng/routing_rules/26

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "routing_rule": {
      "id": 26,
      "name": "rr-1",
      "domain_overrides": [
        {
          "id": 11,
          "domains": [
            "domain-1.com",
            "domain-2.com"
          ],
          "randomization_type": "random",
          "deliver_through": [
            {
              "virtual_mta": {
                "id": 22,
                "name": "ipaddr-1"
              },
              "portion_of_mail": 30.0
            },
            {
              "virtual_mta": {
                "id": 23,
                "name": "ipaddr-2"
              },
              "portion_of_mail": 70.0
            }
          ]
        },
        {
          "id": 12,
          "domains": [
            "domain-3.com",
            "domain-4.com"
          ],
          "randomization_type": "random",
          "deliver_through": [
            {
              "virtual_mta": {
                "id": 25,
                "name": "my-relay-1"
              },
              "portion_of_mail": 100.0
            }
          ]
        }
      ],
      "default": {
        "randomization_type": "random",
        "deliver_through": [
          {
            "virtual_mta": {
              "id": 25,
              "name": "my-relay-1"
            },
            "portion_of_mail": 100.0
          }
        ]
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a Routing Rule

POST /ga/api/v3/eng/routing_rules

Payload

The JSON data sent to this endpoint should contain an object as described in the Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

The response will include a routing_rule key containing the full Routing Rule record as defined in the Routing Rule Attributes section.

Example

POST /ga/api/v3/eng/routing_rules

{
  "routing_rule": {
    "name": "new-routing-rule",
    "domain_overrides": [
      {
        "domains": [
          "new-domain-1.com",
          "new-domain-2.com"
        ],
        "randomization_type": "random",
        "deliver_through": [
          {
            "virtual_mta": {
              "name": "rr-1"
            },
            "portion_of_mail": 29.7712
          },
          {
            "virtual_mta": {
              "id": 32
            },
            "portion_of_mail": "20.2"
          }
        ]
      },
      {
        "domains": [
          "new-domain-3.com",
          "new-domain-4.com"
        ],
        "randomization_type": "random",
        "deliver_through": [
          {
            "virtual_mta": {
              "id": 35,
              "name": "my-relay-1"
            },
            "portion_of_mail": 100.0
          }
        ]
      }
    ],
    "default": {
      "randomization_type": "random",
      "deliver_through": [
        {
          "virtual_mta": {
            "id": 35,
            "name": "my-relay-1"
          },
          "portion_of_mail": 100.0
        }
      ]
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "routing_rule": {
      "id": 42,
      "name": "new-routing-rule",
      "domain_overrides": [
        {
          "id": 21,
          "domains": [
            "new-domain-1.com",
            "new-domain-2.com"
          ],
          "randomization_type": "random",
          "deliver_through": [
            {
              "virtual_mta": {
                "id": 36,
                "name": "rr-1"
              },
              "portion_of_mail": 59.6
            },
            {
              "virtual_mta": {
                "id": 32,
                "name": "ipaddr-1"
              },
              "portion_of_mail": 40.4
            }
          ]
        },
        {
          "id": 22,
          "domains": [
            "new-domain-3.com",
            "new-domain-4.com"
          ],
          "randomization_type": "random",
          "deliver_through": [
            {
              "virtual_mta": {
                "id": 35,
                "name": "my-relay-1"
              },
              "portion_of_mail": 100.0
            }
          ]
        }
      ],
      "default": {
        "randomization_type": "random",
        "deliver_through": [
          {
            "virtual_mta": {
              "id": 35,
              "name": "my-relay-1"
            },
            "portion_of_mail": 100.0
          }
        ]
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Routing Rule

PUT /ga/api/v3/eng/routing_rules/{id}

Payload

routing_rule
hash

This hash is described in the Attributes section of this page, with the exceptions described below.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Exceptions:

domain_overrides array of hashes	This key may not be specified when updating existing Routing Rules. See the Update a Domain Override and Delete a Domain Override sections for information on modifying existing rules.
domain_overrides_new array of hashes	Any overrides provided in this key are treated as new rules to add to the Routing Rule. If any domains provided in those rules already exist in the Routing Rule, this will result in a validation error due to the duplicate domains.

Response

The response will include a routing_rule key containing the full Routing Rule record as defined in the Routing Rule Attributes section.

Example

PUT /ga/api/v3/eng/routing_rules/47

{
  "routing_rule": {
    "name": "routing-rule-new-name",
    "domain_overrides_new": [
      {
        "domains": [
          "new-rule-domain.com"
        ],
        "randomization_type": "message_constant",
        "deliver_through": [
          {
            "virtual_mta": {
              "name": "my-relay-2"
            },
            "portion_of_mail": 100
          }
        ]
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "routing_rule": {
      "id": 47,
      "name": "routing-rule-new-name",
      "domain_overrides": [
        {
          "id": 24,
          "domains": [
            "domain-1.com",
            "domain-2.com"
          ],
          "randomization_type": "random",
          "deliver_through": [
            {
              "virtual_mta": {
                "id": 43,
                "name": "ipaddr-1"
              },
              "portion_of_mail": 30.0
            },
            {
              "virtual_mta": {
                "id": 44,
                "name": "ipaddr-2"
              },
              "portion_of_mail": 70.0
            }
          ]
        },
        {
          "id": 25,
          "domains": [
            "domain-3.com",
            "domain-4.com"
          ],
          "randomization_type": "random",
          "deliver_through": [
            {
              "virtual_mta": {
                "id": 46,
                "name": "my-relay-1"
              },
              "portion_of_mail": 100.0
            }
          ]
        },
        {
          "id": 29,
          "domains": [
            "new-rule-domain.com"
          ],
          "randomization_type": "message_constant",
          "deliver_through": [
            {
              "virtual_mta": {
                "id": 48,
                "name": "my-relay-2"
              },
              "portion_of_mail": 100.0
            }
          ]
        }
      ],
      "default": {
        "randomization_type": "random",
        "deliver_through": [
          {
            "virtual_mta": {
              "id": 46,
              "name": "my-relay-1"
            },
            "portion_of_mail": 100.0
          }
        ]
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Routing Rule

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

Routing Rules that are currently used by other records may not be deleted. Use the VirtualMTAs API to get a list of such records.

References made to Routing Rules from GreenArrow Studio will not prevent deletion of the Routing Rule, but may in the future. Deleting a Routing Rule that is used in GreenArrow Studio by a scheduled/in-progress campaign will cause the campaign to either not send or send with the Default Virtual MTA.

Example

DELETE /ga/api/v3/eng/routing_rules/102

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}

Domain Overrides

Create a Domain Override

POST /ga/api/v3/eng/routing_rules/{routing_rule_id}/domain_overrides

routing_rule_id
integer
/
required

The id for the Routing Rule as supplied when querying the list of Routing Rules.

Payload

domain_override
hash
/
required

The structure of this hash is the same as the entries defined in the domain_overrides array under Routing Rule Attributes.

All required fields must be present. Do not specify read-only fields.

Response

domain_override
hash
/
required

The structure of this hash is the same as the entries defined in the domain_overrides array under Routing Rule Attributes.

Example

POST /ga/api/v3/eng/routing_rules/6/domain_overrides

{
  "domain_override": {
    "domains": [
      "new-domain-1.com",
      "new-domain-2.com",
      "[*.]new-domain-3.com",
      "*.new-domain-4.com"
    ],
    "randomization_type": "email_address_constant",
    "deliver_through": [
      {
        "virtual_mta": {
          "id": 2
        },
        "portion_of_mail": 100
      },
      {
        "virtual_mta": {
          "name": "IPADDR-2"
        },
        "portion_of_mail": 25
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain_override": {
      "id": 5,
      "domains": [
        "new-domain-1.com",
        "new-domain-2.com",
        "[*.]new-domain-3.com",
        "*.new-domain-4.com"
      ],
      "randomization_type": "email_address_constant",
      "deliver_through": [
        {
          "virtual_mta": {
            "id": 2,
            "name": "ipaddr-1"
          },
          "portion_of_mail": 80.0
        },
        {
          "virtual_mta": {
            "id": 3,
            "name": "ipaddr-2"
          },
          "portion_of_mail": 20.0
        }
      ]
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Domain Override

PUT /ga/api/v3/eng/routing_rules/{routing_rule_id}/domain_overrides/{override_id}

routing_rule_id integer / required	The `id` for the Routing Rule as supplied when querying the list of Routing Rules.
override_id integer / required	The `id` for the Domain Override as supplied in the `domain_overrides` array when querying details on a single Routing Rule.

Payload

domain_override
hash
/
required

The structure of this hash is the same as the entries defined in the domain_overrides array under Routing Rule Attributes.

Response

domain_override
hash
/
required

The structure of this hash is the same as the entries defined in the domain_overrides array under Routing Rule Attributes.

Example

PUT /ga/api/v3/eng/routing_rules/20/domain_overrides/10

{
  "domain_override": {
    "domains": [
      "new-domain-1a.com",
      "new-domain-2a.com"
    ],
    "randomization_type": "email_address_constant",
    "deliver_through": [
      {
        "virtual_mta": {
          "id": 17
        },
        "portion_of_mail": 100
      },
      {
        "virtual_mta": {
          "name": "IPADDR-1"
        },
        "portion_of_mail": 300
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain_override": {
      "id": 10,
      "domains": [
        "new-domain-1a.com",
        "new-domain-2a.com"
      ],
      "randomization_type": "email_address_constant",
      "deliver_through": [
        {
          "virtual_mta": {
            "id": 16,
            "name": "ipaddr-1"
          },
          "portion_of_mail": 75.0
        },
        {
          "virtual_mta": {
            "id": 17,
            "name": "ipaddr-2"
          },
          "portion_of_mail": 25.0
        }
      ]
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Domain Override

DELETE /ga/api/v3/eng/routing_rules/{routing_rule_id}/domain_overrides/{override_id}

Example

DELETE /ga/api/v3/eng/routing_rules/102

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}