GreenArrow Email Software Documentation

IP Addresses API

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.

name

string

/

optional

Match only IP Addresses whose name matches (case-insensitively) the given value.

ip

string

/

optional

Match only IP Addresses whose IP matches the given value.

hostname

string

/

optional

Match only IP Addresses whose hostname matches (case-insensitively) the given value.

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
}


Copyright © 2012–2024 GreenArrow Email