Relay Servers API

Table of Contents
Overview
Attributes
Get a list of Relay Servers
Get all Details About a Single Relay Server
Create a Relay Server
Update a Relay Server
Delete a Relay Server

Overview

Relay Servers are VirtualMTAs that enable GreenArrow Engine to function as an SMTP client. They can be used to inject messages into both GreenArrow and non-GreenArrow SMTP servers.

Attributes

The following attributes are defined for Relay Servers:

relay_server
hash
/
required

id
integer
/
read-only

An automatically generated identifier.

name
string
/
required

A descriptive name to associate with this Throttling Template.

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.

source_ip
hash
/
required

This hash defines details about local connection parameters to the destination server.

ip
string
/
required

The outgoing IP address to use when connecting to the destination server.

Must be a valid IPv4 address in dotted-decimal notation.

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 start and end with a letter or number.

destination
hash

This hash defines details about the destination server.

hostname string / required	Hostname or IP address of the destination server. Must be from 1 to 200 characters in length. Must start and end with a letter or number.
port integer / required	Port number on the destination server. Must be an integer from 1 to 65535.
username string / default: `null`	Username to use for authentication on the destination server. If this is `null`, authentication will not be used. May be a maximum of 200 characters in length.
password string / default: `null`	Password to use for authentication on the destination server. If this is `null`, authentication will not be used. May be a maximum of 200 characters in length.

throttle_limits
hash

max_concurrent_connections
integer
/
required

The maximum number of connections allowed to the destination server.

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 the destination server.

The value 0 is treated as unlimited.

Must be an integer greater than or equal to 0.

redirect
hash
/
default: null

This field will cause delivery intended for this Relay Server 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 being redirected to.
name string	The case-insensitive `name` of the VirtualMTA that is being redirected to. If both `id` and `name` are present when creating or updating a Relay Server, the value in `name` is ignored.

Get a list of Relay Servers

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

The response will contain a list of Relay Servers in the following format.

relay_servers
array of hashes

id integer	An automatically generated identifier.
name string	A descriptive name associated with this Relay Server.

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

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "relay_servers": [
      {
        "id": 4,
        "name": "relay-1"
      },
      {
        "id": 5,
        "name": "relay-2"
      },
      {
        "id": 6,
        "name": "relay-3"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get all Details About a Single Relay Server

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

Response

relay_server
hash

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

Example

GET /ga/api/v3/eng/relay_servers/16

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "relay_server": {
      "id": 16,
      "name": "relay-1",
      "source_ip": {
        "ip": "127.0.0.2",
        "hostname": "outgoing-hostname.com"
      },
      "destination": {
        "hostname": "destination-hostname.com",
        "port": 26,
        "username": "myusername",
        "password": "mysecret"
      },
      "throttle_limits": {
        "max_concurrent_connections": 2,
        "max_messages_per_hour": 120
      },
      "redirect": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a Relay Server

POST /ga/api/v3/eng/relay_servers

Payload

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

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

Response

The response will include a relay_server key containing the full Relay Server record as defined in Relay Server Attributes.

Example

POST /ga/api/v3/eng/relay_servers

{
  "relay_server": {
    "name": "new-relay-server",
    "source_ip": {
      "ip": "127.0.0.2",
      "hostname": "outgoing-hostname.com"
    },
    "destination": {
      "hostname": "destination-hostname.com",
      "port": 25,
      "username": "myusername",
      "password": "mysecret"
    },
    "throttle_limits": {
      "max_concurrent_connections": 2,
      "max_messages_per_hour": 120
    },
    "redirect": {
      "name": "ipaddr-1"
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "relay_server": {
      "id": 26,
      "name": "new-relay-server",
      "source_ip": {
        "ip": "127.0.0.2",
        "hostname": "outgoing-hostname.com"
      },
      "destination": {
        "hostname": "destination-hostname.com",
        "port": 25,
        "username": "myusername",
        "password": "mysecret"
      },
      "throttle_limits": {
        "max_concurrent_connections": 2,
        "max_messages_per_hour": 120
      },
      "redirect": {
        "type": "ip_address",
        "id": 20,
        "name": "ipaddr-1"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Relay Server

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

Payload

relay_server
hash

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

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

Response

The response will include a relay_server key containing the full Relay Server record as defined in Relay Server Attributes.

Example

PUT /ga/api/v3/eng/relay_servers/29

{
  "relay_server": {
    "name": "updated-relay-server",
    "source_ip": {
      "ip": "127.0.0.7",
      "hostname": "updated-outgoing-hostname.com"
    },
    "destination": {
      "hostname": "updated-destination-hostname.com",
      "port": 1025,
      "username": "updated-myusername",
      "password": "updated-mysecret"
    },
    "throttle_limits": {
      "max_concurrent_connections": 5,
      "max_messages_per_hour": 500
    },
    "redirect": null
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "relay_server": {
      "id": 29,
      "name": "updated-relay-server",
      "source_ip": {
        "ip": "127.0.0.7",
        "hostname": "updated-outgoing-hostname.com"
      },
      "destination": {
        "hostname": "updated-destination-hostname.com",
        "port": 1025,
        "username": "updated-myusername",
        "password": "updated-mysecret"
      },
      "throttle_limits": {
        "max_concurrent_connections": 5,
        "max_messages_per_hour": 500
      },
      "redirect": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Relay Server

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

Relay Servers 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 Relay Servers from GreenArrow Studio will not prevent deletion of the Relay Server, but may in the future. Deleting a Relay Server 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/relay_servers/41

HTTP/1.1 200 OK

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