<img src="https://d5nxst8fruw4z.cloudfront.net/atrk.gif?account=lYCzn1QolK10N8" style="display:none" height="1" width="1" alt="">

Throttle Programs API

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. This will typically be rounded up to the nearest 5 minutes

  • Must be a positive integer
notify

string

/

default: null

An email address to notify when the backoff state changes.

  • Must be null or an email address.
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,
        "notify": "admin@example.com",
        "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,
      "notify": "admin@example.com",
      "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,
        "notify": "admin@example.com",
        "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,
        "notify": "admin@example.com",
        "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
}