IP Addresses API

Table of Contents
Overview
Attributes
IP Addresses
Throttling Rules

Overview

IP Addresses contain two sets of Throttling Rules. The Throttling Rules provided by the Throttling Template can be overridden by rules on the IP Address record. Each Throttling Rule contains a list of domains to which it applies.

When email is delivered, the Throttling Template and IP Address rules are combined to determine what throttling limits are applied.

Attributes

ip_address
hash

id
integer
/
read-only

An automatically generated identifier.

name
string
/
required

A descriptive name to associate with this IP Address.

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.

ip
string
/
required

The IPv4 address in dotted-decimal notation (e.g. 10.15.200.2).

Must be a valid dotted-decimal IPv4 address string
It is not required that the address be active

hostname
string
/
required

The hostname to used in the HELO or HELO command of outgoing SMTP connections. (This should be the reverse DNS name for the IP address that’s being used to connect to the Relay Server.)

Must be from 1 to 200 characters in length
Must contain only letters, numbers, and -
Must start and end with a letter or number
Must not be an IPv4 address

delivery_paused
boolean
/
default: false

Pause deliveries to this IP address. The effect is similar to pausing individual sends in Engine’s user interface, but applies to an entire IP address.

While an IP is paused, all delivery attempts will defer with the message Delivery paused..

If an IP address is both paused and redirected, the pause will take priority and delivery attempts will be paused.

redirect
hash
/
default: null

This field will cause delivery intended for this IP Address to instead be sent through a different VirtualMTA.

type string / read-only	The type of VirtualMTA that is the redirect destination. This may be `ip_address`, `relay_server`, or `routing_rule`.
id integer	The `id` of the VirtualMTA that is the redirect destination.
name string	The case-insensitive `name` of the VirtualMTA that is the redirect destination. If both `id` and `name` are present when creating or updating an IP Address, the value in `name` is ignored.

throttling_template
hash
/
required

When reading an IP Address, this hash will contain the full definition of the current Throttling Template.

id integer	The `id` of the Throttling Template from which to inherit.
name string	The case-insensitive `name` of the Throttling Template from which to inherit. If both `id` and `name` are present when creating or updating an IP Address, the value in `name` is ignored.

rules
array of hashes

A list of throttling rules. An IP Address may contain up to 250 throttling rules.

id
integer
/
read-only

The internal identifier for this rule row. Use this value when calling the Update Throttling Rule endpoint.

domains
array of strings
/
required

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 IP

max_concurrent_connections
integer
/
required

The maximum number of connections allowed to each domain in this rule.

The value 0 is treated as unlimited.

Must be an integer greater than or equal to 0.

max_messages_per_hour
integer
/
required

The maximum number of messages per hour allowed to each domain in this rule.

The value 0 is treated as unlimited.

Must be an integer greater than or equal to 0.

throttle_program
hash
/
default: null

The Throttle Program to use on this rule. Set to null to use no Throttle Program.

If this is non-null, the requested Throttle Program must exist.

id
integer

The identifier of the Throttle Program.

name:
string

The descriptive name for the Throttle Program. If this is specified to set the Throttle Program for this Throttling Rule, the Throttle Program is found with a case-insensitive search.

If both id and name are present when creating or updating a rule, the value in name is ignored and the requested program will only be found by its id.

default
hash

max_concurrent_connections
integer
/
default: null

The maximum number of connections allowed to domains not specified in a rule.

The value 0 is treated as unlimited. The value null will use the default as defined in the Throttling Template.

Must be null or an integer greater than or equal to 0.

max_messages_per_hour
integer
/
default: null

The maximum number of messages per hour allowed to domains not specified in a rule.

The value 0 is treated as unlimited. The value null will use the default as defined in the Throttling Template.

Must be null or an integer greater than or equal to 0.

IP Addresses

Get a List of IP Addresses

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

ip_addresses
array of hashes

id integer	An automatically generated identifier.
name string	A descriptive name associated with this IP Address.

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

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "ip_addresses": [
      {
        "id": 2,
        "name": "ipaddr-1"
      },
      {
        "id": 3,
        "name": "ipaddr-2"
      },
      {
        "id": 5,
        "name": "ipaddr-3"
      }
    ],
    "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 IP Address

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

Response

ip_address
hash

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

Example

GET /ga/api/v3/eng/ip_addresses/12

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "ip_address": {
      "id": 12,
      "name": "ipaddr-1",
      "ip": "10.0.0.28",
      "hostname": "hostname-28.com",
      "delivery_paused": false,
      "redirect": null,
      "throttling_template": {
        "id": 3,
        "name": "Basic Throttling Template"
      },
      "rules": [
        {
          "id": 11,
          "domains": [
            "ip1-domain1.com",
            "ip1-domain2.com"
          ],
          "max_concurrent_connections": 2,
          "max_messages_per_hour": 70,
          "throttle_program": null
        },
        {
          "id": 12,
          "domains": [
            "ip1-domain3.com",
            "ip1-domain4.com"
          ],
          "max_concurrent_connections": 0,
          "max_messages_per_hour": 20,
          "throttle_program": null
        }
      ],
      "default": {
        "max_concurrent_connections": null,
        "max_messages_per_hour": null
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Create an IP Address

POST /ga/api/v3/eng/ip_addresses

Payload

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

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

Response

The response will include an ip_address key containing the full IP Address record as defined in IP Address Attributes.

Example

POST /ga/api/v3/eng/ip_addresses

{
  "ip_address": {
    "name": "ipaddr-4",
    "ip": "127.0.0.9",
    "hostname": "new-ip-example.com",
    "throttling_template": {
      "name": "Basic Throttling Template"
    },
    "delivery_paused": true,
    "redirect": {
      "id": 21
    },
    "rules": [
      {
        "domains": [
          "example-2.com",
          "example-1.com"
        ],
        "max_concurrent_connections": 2,
        "max_messages_per_hour": 0,
        "throttle_program": {
          "id": 1,
          "name": "this name doesn't exist"
        }
      },
      {
        "domains": [
          "example-6.com",
          "example-7.com"
        ],
        "max_concurrent_connections": 0,
        "max_messages_per_hour": 500,
        "throttle_program": {
          "name": "Automatic Backoff"
        }
      }
    ],
    "default": {
      "max_concurrent_connections": 1,
      "max_messages_per_hour": null
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "ip_address": {
      "id": 22,
      "name": "ipaddr-4",
      "ip": "127.0.0.9",
      "hostname": "new-ip-example.com",
      "delivery_paused": true,
      "redirect": {
        "type": "relay_server",
        "id": 21,
        "name": "relay-1"
      },
      "throttling_template": {
        "id": 4,
        "name": "Basic Throttling Template"
      },
      "rules": [
        {
          "id": 17,
          "domains": [
            "example-2.com",
            "example-1.com"
          ],
          "max_concurrent_connections": 2,
          "max_messages_per_hour": 0,
          "throttle_program": {
            "id": 1,
            "name": "Automatic Backoff"
          }
        },
        {
          "id": 18,
          "domains": [
            "example-6.com",
            "example-7.com"
          ],
          "max_concurrent_connections": 0,
          "max_messages_per_hour": 500,
          "throttle_program": {
            "id": 1,
            "name": "Automatic Backoff"
          }
        }
      ],
      "default": {
        "max_concurrent_connections": 1,
        "max_messages_per_hour": null
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update an IP Address

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

Payload

The payload to this endpoint is the same as described in the Attributes section of this page, with the exceptions described below.

throttling_template
hash
/
required

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

Exceptions:

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

Response

The response will include an ip_address key containing the full IP Address record as defined in IP Address Attributes.

Example

PUT /ga/api/v3/eng/ip_addresses/23

{
  "ip_address": {
    "name": "ipaddr-new-name",
    "rules_new": [
      {
        "domains": [
          "new-rule-domain.com"
        ],
        "max_concurrent_connections": 7,
        "max_messages_per_hour": 1056
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "ip_address": {
      "id": 23,
      "name": "ipaddr-new-name",
      "ip": "10.0.0.34",
      "hostname": "hostname-34.com",
      "delivery_paused": false,
      "redirect": null,
      "throttling_template": {
        "id": 5,
        "name": "Basic Throttling Template"
      },
      "rules": [
        {
          "id": 21,
          "domains": [
            "ip1-domain1.com",
            "ip1-domain2.com"
          ],
          "max_concurrent_connections": 2,
          "max_messages_per_hour": 70,
          "throttle_program": null
        },
        {
          "id": 22,
          "domains": [
            "ip1-domain3.com",
            "ip1-domain4.com"
          ],
          "max_concurrent_connections": 0,
          "max_messages_per_hour": 20,
          "throttle_program": null
        },
        {
          "id": 23,
          "domains": [
            "new-rule-domain.com"
          ],
          "max_concurrent_connections": 7,
          "max_messages_per_hour": 1056,
          "throttle_program": null
        }
      ],
      "default": {
        "max_concurrent_connections": null,
        "max_messages_per_hour": null
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete an IP Address

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

IP Addresses 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 IP Addresses from GreenArrow Studio will not prevent deletion of the IP Address, but may in the future. Deleting an IP Address 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.

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/ip_addresses/46

HTTP/1.1 200 OK

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

Throttling Rules

Create a Throttling Rule

POST /ga/api/v3/eng/ip_addresses/{ip_address_id}/throttling_rules

Parameters

ip_address_id
integer
/
required

The id for an IP Address as supplied when querying the list of IP Addresses.

Payload

throttling_rule
hash
/
required

The structure of this hash is the same as the entries defined in the rules array under IP Address Attributes.

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

Response

The response will include a throttling_rule key containing a hash that uses the structure defined in the IP Address Attributes.

Example

POST /ga/api/v3/eng/ip_addresses/2/throttling_rules

{
  "throttling_rule": {
    "domains": [
      "new-domain-1.com",
      "new-domain-2.com"
    ],
    "throttle_program": {
      "name": "Automatic Backoff"
    },
    "max_concurrent_connections": 7,
    "max_messages_per_hour": 9
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_rule": {
      "id": 3,
      "domains": [
        "new-domain-1.com",
        "new-domain-2.com"
      ],
      "max_concurrent_connections": 7,
      "max_messages_per_hour": 9,
      "throttle_program": {
        "id": 4,
        "name": "Automatic Backoff"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Throttling Rule

PUT /ga/api/v3/eng/ip_addresses/{ip_address_id}/throttling_rules/{rule_id}

ip_address_id integer / required	The `id` for a IP Address as supplied when querying the list of IP Addresses.
rule_id integer / required	The `id` for a Throttling Rule as supplied in the `rules` array when querying details on a single IP Address.

Payload

throttling_rule
hash
/
required

The structure of this hash is the same as the entries defined in the rules array under IP Address Attributes.

Response

The response will include an ip_address key containing the full IP Address record as defined in IP Address Attributes.

Example

PUT /ga/api/v3/eng/ip_addresses/4/throttling_rules/4

{
  "throttling_rule": {
    "domains": [
      "new-domain-1.com",
      "new-domain-2.com"
    ],
    "max_concurrent_connections": 7,
    "max_messages_per_hour": 9
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_rule": {
      "id": 4,
      "domains": [
        "new-domain-1.com",
        "new-domain-2.com"
      ],
      "max_concurrent_connections": 7,
      "max_messages_per_hour": 9,
      "throttle_program": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Throttling Rule

Use this endpoint to remove a rule from an IP Address.

DELETE /ga/api/v3/eng/ip_addresses/{ip_address_id}/throttling_rules/{rule_id}

ip_address_id integer / required	The `id` for a IP Address as supplied when querying the list of IP Addresses.
rule_id integer / required	The `id` for a Throttling Rule as supplied in the `rules` array when querying details on a single IP Address.

Example

DELETE /ga/api/v3/eng/ip_addresses/14/throttling_rules/14

HTTP/1.1 200 OK

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