GreenArrow Email Software Documentation

Throttles API

Overview

Throttles are GreenArrow’s mechanism for limiting the volume of mail that should be delivered in a span of time to a single destination.

Attributes

The following attributes are defined for throttles:

throttle

hash
id

integer

The internal primary key of this throttle.
ip_address

hash
id

integer

The ID of the IP address to which this throttle belongs.
name

string

The name of the IP address to which this throttle belongs.
throttling_rule

hash

Details about the throttling rule that resulted in this throttle being created. This may be a rule on either an IP Address or a Throttling Template.

type

string

This value will be either ip_address or throttling_template. This indicates whether the rule exists on an IP Address or a Throttling Template.
id

integer

The ID of the throttling rule.
ip_address

hash

This key will only be present if type=ip_address.

id

integer

The ID of the IP Address which contains this throttling rule.
name

string

The name of the IP Address which contains this throttling rule.
throttling_template

hash

This key will only be present if type=throttling_template.

id

integer

The ID of the Throttling Template which contains this throttling rule.
name

string

The name of the Throttling Template which contains this throttling rule.
normal_max_messages_per_hour

integer

The maximum number of messages per hour that this throttle will deliver when not in backoff mode.
normal_max_concurrent_connections

integer

The maximum number concurrent connections that this throttle will establish when not in backoff mode.
domains

array of strings

This is the list of domain and domain rules that are configured for the throttle (i.e. not all of the domain names that might be matched by the rule). So if the throttling rule includes mx:*.yahoodns.net – then that is the string that will appear here (not for example yahoo.com).

This list can include anything that goes into the domains list of a throttling rule. This includes MX rules and wildcards (e.g. mx:[*.]yahoodns.net).

This list is the effective list of domains. This means that for a throttle defined on a Throttling Template, domains that are overrided by an IP address will be excluded.

For example, if the Throttling Template includes the domains greenarrowemail.com, drh.net, yet the IP address using that Throttling Template only overrides drh.net, then the following is true: For the IP Address, there will be two throttles: one associated with the Throttling Template’s throttling rule greenarrowemail.com, and one associated with the IP Address’s throttling rule drh.net.
in_backoff

boolean

The throttle is currently in backoff mode. This may be either due to a throttle program or the smtp_match_begin_backoff_mode configuration directive.
backoff_reason

string

The reason the throttle is in backoff mode (if it is). This can be null, "throttle_program", or "regex_match".
backoff_began_at

time string

The time that backoff began. This will be null if the throttle is not currently in backoff mode. This time will be in the engine_time_zone.
backoff_ends_at

time string

The time that backoff will end. This will be null if the throttle is not currently in backoff mode. This time will be in the engine_time_zone.
backoff_max_messages_per_hour

integer

The maximum number of messages per hour that this throttle will currently deliver in backoff mode.

This will be null if the throttle is not currently in backoff mode.
backoff_max_concurrent_connections

integer

The maximum number concurrent connections that this throttle will currently establish in backoff mode.

This will be null if the throttle is not currently in backoff mode.

Get a list of throttles that are currently in backoff mode

GET /ga/api/v3/eng/throttles_in_backoff

throttles

array

An array of throttle objects as defined above.
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/throttles_in_backoff?in_backoff=1


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "throttles": [
      {
        "id": 5,
        "ip_address": {
          "id": 3,
          "name": "ipaddr-1"
        },
        "throttling_rule": {
          "type": "ip_address",
          "id": 5,
          "ip_address": {
            "id": 3,
            "name": "ipaddr-1"
          }
        },
        "normal_max_messages_per_hour": 0,
        "normal_max_concurrent_connections": 0,
        "domains": [
          "def.net",
          "xyz.net"
        ],
        "in_backoff": true,
        "backoff_reason": "throttle_program",
        "backoff_began_at": "2022-06-29T14:35:20-04:00",
        "backoff_ends_at": "2022-06-29T14:40:20-04:00",
        "backoff_max_messages_per_hour": 60,
        "backoff_max_concurrent_connections": 1
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 1,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get a list of throttles on an IP address

GET /ga/api/v3/eng/ip_addresses/{ip_address_id}/throttles

throttles

array

An array of throttle objects as defined above.
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/ip_addresses/2/throttles


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "throttles": [
      {
        "id": 1,
        "ip_address": {
          "id": 2,
          "name": "ipaddr-1"
        },
        "throttling_rule": {
          "type": "ip_address",
          "id": 1,
          "ip_address": {
            "id": 2,
            "name": "ipaddr-1"
          }
        },
        "normal_max_messages_per_hour": 0,
        "normal_max_concurrent_connections": 0,
        "domains": [
          "abc.net"
        ],
        "in_backoff": false,
        "backoff_reason": null,
        "backoff_began_at": null,
        "backoff_ends_at": null,
        "backoff_max_messages_per_hour": null,
        "backoff_max_concurrent_connections": null
      },
      {
        "id": 2,
        "ip_address": {
          "id": 2,
          "name": "ipaddr-1"
        },
        "throttling_rule": {
          "type": "ip_address",
          "id": 2,
          "ip_address": {
            "id": 2,
            "name": "ipaddr-1"
          }
        },
        "normal_max_messages_per_hour": 0,
        "normal_max_concurrent_connections": 0,
        "domains": [
          "def.net",
          "xyz.net"
        ],
        "in_backoff": false,
        "backoff_reason": null,
        "backoff_began_at": null,
        "backoff_ends_at": null,
        "backoff_max_messages_per_hour": null,
        "backoff_max_concurrent_connections": null
      },
      {
        "id": 3,
        "ip_address": {
          "id": 2,
          "name": "ipaddr-1"
        },
        "throttling_rule": {
          "type": "throttling_template",
          "id": 3,
          "throttling_template": {
            "id": 1,
            "name": "Basic Throttling Template"
          }
        },
        "normal_max_messages_per_hour": 0,
        "normal_max_concurrent_connections": 0,
        "domains": [
          "zed.net"
        ],
        "in_backoff": false,
        "backoff_reason": null,
        "backoff_began_at": null,
        "backoff_ends_at": null,
        "backoff_max_messages_per_hour": null,
        "backoff_max_concurrent_connections": null
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get a throttle on an IP address by domain name

GET /ga/api/v3/eng/ip_addresses/{ip_address_id}/throttles/by_domain/{domain}

Retrieves the status of a throttle on an IP address for a specific domain name. The domain name can be any of the domains listed in the throttle’s throttling rule. Wildcard expansion is not performed – so you would specify *.example.com to match a throttle that includes *.example.com (not something.example.com).

If no such throttle was found, the throttle key will be returned having a null value.

Example

GET /ga/api/v3/eng/ip_addresses/5/throttles/by_domain/XYZ.Net


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "throttle": {
      "id": 7,
      "ip_address": {
        "id": 5,
        "name": "ipaddr-1"
      },
      "throttling_rule": {
        "type": "ip_address",
        "id": 7,
        "ip_address": {
          "id": 5,
          "name": "ipaddr-1"
        }
      },
      "normal_max_messages_per_hour": 0,
      "normal_max_concurrent_connections": 0,
      "domains": [
        "def.net",
        "ghi.net",
        "xyz.net"
      ],
      "in_backoff": false,
      "backoff_reason": null,
      "backoff_began_at": null,
      "backoff_ends_at": null,
      "backoff_max_messages_per_hour": null,
      "backoff_max_concurrent_connections": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Take a throttle out of backoff mode

POST /ga/api/v3/eng/ip_addresses/{ip_address_id}/throttles/{throttle_id}/take_out_of_backoff

If the throttle is currently in backoff mode, take it out of backoff mode.

Example

POST /ga/api/v3/eng/ip_addresses/10/throttles/16/take_out_of_backoff


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "was_in_backoff": true,
    "is_in_backoff": false
  },
  "error_code": null,
  "error_messages": null
}

 Routing Rules API
Throttle Programs API 

Copyright © 2012–2024 GreenArrow Email