GreenArrow Email Software Documentation

Relay Servers API

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
}


Copyright © 2012–2024 GreenArrow Email