<img src="https://d5nxst8fruw4z.cloudfront.net/atrk.gif?account=lYCzn1QolK10N8" style="display:none" height="1" width="1" alt="">

VirtualMTAs API

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
}