GreenArrow Email Software Documentation

Routing Rules API

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
}


Copyright © 2012–2024 GreenArrow Email