VirtualMTAs API

Table of Contents
Overview
Get a list of all VirtualMTAs
List the References to a VirtualMTA
Get the Default VirtualMTA
Set the Default VirtualMTA

Overview

A VirtualMTA is a path that mail takes to reach its destination.

IP Address - A single IP address that is used to send messages.
Relay Server - An SMTP relay server that GreenArrow Engine forwards messages onto. This could be another GreenArrow Engine installation or any other SMTP server that is configured to accept messages.
Routing Rule - A group of one or more IP Addresses, Relay Servers and/or other Routing Rules. Routing Rules are most commonly used to load balance outgoing messages over multiple IP addresses.

Every VirtualMTA has three fields in common: type, id, and name. The id and name columns are unique (case-insensitive) across all types of VirtualMTAs.

Get a list of all VirtualMTAs

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

virtual_mtas
array of hashes

type
string

The type of VirtualMTA.

May be: ip_address, relay_server, or routing_rule

id
integer

The unique identifier for this VirtualMTA. These identifiers will be unique across all types of VirtualMTAs.

name
string

The user-supplied name for this VirtualMTA. This is case-insensitive unique across all types of VirtualMTAs.

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

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "virtual_mtas": [
      {
        "type": "ip_address",
        "id": 2,
        "name": "ipaddr-1"
      },
      {
        "type": "ip_address",
        "id": 3,
        "name": "ipaddr-2"
      },
      {
        "type": "relay_server",
        "id": 4,
        "name": "my-relay-1"
      },
      {
        "type": "relay_server",
        "id": 5,
        "name": "my-relay-2"
      },
      {
        "type": "routing_rule",
        "id": 6,
        "name": "rr-1"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 5,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

List the References to a VirtualMTA

GET /ga/api/v3/eng/virtual_mtas/{id}/used_by
GET /ga/api/v3/eng/virtual_mtas/{id}/used_by?page={page}
GET /ga/api/v3/eng/virtual_mtas/{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 IP Address.

This list does not include any references made by GreenArrow Studio, but it may in the future.

type
string

The type of object.

May be: default_virtual_mta, ip_address, relay_server, routing_rule, or mail_class

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/virtual_mtas/2/used_by

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "used_by": [
      {
        "type": "default_virtual_mta",
        "id": 1,
        "name": "Default VirtualMTA"
      },
      {
        "type": "ip_address",
        "id": 3,
        "name": "ipaddr-2"
      },
      {
        "type": "relay_server",
        "id": 4,
        "name": "relay-1"
      },
      {
        "type": "relay_server",
        "id": 5,
        "name": "relay-2"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 4,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get the Default VirtualMTA

The default VirtualMTA is the VirtualMTA used for email that does not have a VirtualMTA assigned or is assigned a VirtualMTA name that does not exist.

GET /ga/api/v3/eng/virtual_mtas/default

Response

default_virtual_mta
hash

type
string

The type of VirtualMTA.

May be: ip_address, relay_server, or routing_rule

id
integer

The unique identifier for the VirtualMTA.

name
string

The user-supplied name for the VirtualMTA. If both id and name are supplied, the value in name is ignored.

Example

GET /ga/api/v3/eng/virtual_mtas/default

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "default_virtual_mta": {
      "type": "ip_address",
      "id": 17,
      "name": "ipaddr-1"
    }
  },
  "error_code": null,
  "error_messages": null
}

Set the Default VirtualMTA

PUT /ga/api/v3/eng/virtual_mtas/default

Payload

default_virtual_mta
hash

id integer	The unique identifier for the VirtualMTA.
name string	The user-supplied name for the VirtualMTA. If both `id` and `name` are supplied, the value in `name` is ignored.

Response

If the update is successful, the response is the same as Get the default VirtualMTA.

Example

PUT /ga/api/v3/eng/virtual_mtas/default

{
  "default_virtual_mta": {
    "name": "rr-1"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "default_virtual_mta": {
      "type": "routing_rule",
      "id": 26,
      "name": "rr-1"
    }
  },
  "error_code": null,
  "error_messages": null
}