Throttle Programs API

Table of Contents
Overview
Attributes
Get a List of Throttle Programs
Get Details on a Single Throttle Program
List the References to a Throttle Program
Create a Throttle Program
Update a Throttle Program
Delete a Throttle Program

Overview

Throttle Programs are used to control the rate that email deliveries are attempted when an ISP is not accepting email normally.

If an ISP is accepting email normally, then email delivery is attempted at the full speed configured in the IP Address or Throttle Template.

See Dynamic Delivery for more information on how Dynamic Delivery operates.

Attributes

The following attributes are defined for Throttle Programs:

throttle_program
hash

id
integer
/
read-only

An automatically generated identifier.

name
string
/
required

A descriptive name to associate with this Throttle Program.

Must be unique (case-insensitive)
Must be from 1 to 200 characters in length
Must contain at least one letter or number

builtin
boolean
/
read-only

This value is true if this Throttle Program is built into the software. If this value is true, it cannot be updated or removed.

backoff
hash

max_concurrent_connections
hash

mode
string
/
required

Define how the value should be used.

May be: percent or fixed

value
integer
/
required

Must be a positive integer

max_messages_per_hour
hash

mode
string
/
required

Define how the value should be used.

May be: percent or fixed

value
integer
/
required

Must be a positive integer

return_after
integer
/
required

The number of seconds to stay in backoff once it begins.

Must be a positive integer

triggers
hash

Define how this Throttle Program is triggered. All Throttle Programs must have at least one trigger specified (either failure_rate or deferral_rate).

failure_rate
integer
/
default: null

The percentage of messages that are failures to trigger backoff mode.

Must be null or a positive integer from 1 to 100.

deferral_rate
integer
/
default: null

The percentage of messages that are deferrals to trigger backoff mode.

Must be null or a positive integer from 1 to 100.

required_attempts
integer
/
required

The number of delivery attempts that must take place in a 5-minute window to trigger backoff mode.

Must be a positive integer

Get a List of Throttle Programs

GET /ga/api/v3/eng/throttle_programs
GET /ga/api/v3/eng/throttle_programs?page={page}
GET /ga/api/v3/eng/throttle_programs?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

throttle_programs
array of hashes

id integer	An automatically generated identifier.
name string	A descriptive name associated with this Throttle Program.

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

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttle_programs": [
      {
        "id": 1,
        "name": "Automatic Backoff"
      },
      {
        "id": 2,
        "name": "Second Throttle Program"
      },
      {
        "id": 3,
        "name": "Third Throttle Program"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Details on a Single Throttle Program

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

Response

throttle_program
hash

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

Example

GET /ga/api/v3/eng/throttle_programs/10

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttle_program": {
      "id": 10,
      "name": "Automatic Backoff",
      "builtin": false,
      "backoff": {
        "max_concurrent_connections": {
          "mode": "fixed",
          "value": 3
        },
        "max_messages_per_hour": {
          "mode": "percent",
          "value": 25
        },
        "return_after": 720,
        "triggers": {
          "failure_rate": 25,
          "deferral_rate": null,
          "required_attempts": 50
        }
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

List the References to a Throttle Program

GET /ga/api/v3/eng/throttle_programs/{id}/used_by
GET /ga/api/v3/eng/throttle_programs/{id}/used_by?page={page}
GET /ga/api/v3/eng/throttle_programs/{id}/used_by?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

used_by
array of hashes

A list of objects that use this Throttle Program.

type
string

The type of object.

May be: throttling_template or ip_address

id
integer

The unique identifier for the object.

name
string

The user-supplied case-insensitive unique identifier for the object.

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/throttle_programs/1/used_by

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "used_by": [
      {
        "type": "ip_address",
        "id": 2,
        "name": "ipaddr-1"
      },
      {
        "type": "throttling_template",
        "id": 1,
        "name": "Basic Template"
      },
      {
        "type": "throttling_template",
        "id": 2,
        "name": "Second Template"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a Throttle Program

POST /ga/api/v3/eng/throttle_programs

Payload

throttle_program
hash
/
required

This hash is described in the Throttle Program Attributes section of this page.

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

Response

throttle_program
hash

This hash is described in the Throttle Program Attributes section of this page.

Example

POST /ga/api/v3/eng/throttle_programs

{
  "throttle_program": {
    "name": "New Throttle Program",
    "backoff": {
      "max_concurrent_connections": {
        "mode": "percent",
        "value": 50
      },
      "max_messages_per_hour": {
        "mode": "fixed",
        "value": 10
      },
      "return_after": 720,
      "triggers": {
        "failure_rate": null,
        "deferral_rate": 30,
        "required_attempts": 75
      }
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttle_program": {
      "id": 16,
      "name": "New Throttle Program",
      "builtin": false,
      "backoff": {
        "max_concurrent_connections": {
          "mode": "percent",
          "value": 50
        },
        "max_messages_per_hour": {
          "mode": "fixed",
          "value": 10
        },
        "return_after": 720,
        "triggers": {
          "failure_rate": null,
          "deferral_rate": 30,
          "required_attempts": 75
        }
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Throttle Program

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

Payload

throttle_program
hash
/
required

This hash is described in the Throttle Program Attributes section of this page.

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

Response

throttle_program
hash

This hash is described in the Throttle Program Attributes section of this page.

Example

PUT /ga/api/v3/eng/throttle_programs/17

{
  "throttle_program": {
    "name": "Updated Throttle Program"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttle_program": {
      "id": 17,
      "name": "Updated Throttle Program",
      "builtin": false,
      "backoff": {
        "max_concurrent_connections": {
          "mode": "fixed",
          "value": 3
        },
        "max_messages_per_hour": {
          "mode": "percent",
          "value": 25
        },
        "return_after": 720,
        "triggers": {
          "failure_rate": 25,
          "deferral_rate": null,
          "required_attempts": 50
        }
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Throttle Program

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

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

Response

The response is a standard success or error message.

Example

DELETE /ga/api/v3/eng/throttle_programs/25

HTTP/1.1 200 OK

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