Mailgun-Compatible IP Pool API

• Table of Contents
• Overview
• Authentication
• Requests and Responses
• Common Fields
• Get a List of IP Pools
• Create an IP Pool
• Identifiers
• Differences from Mailgun

Overview

The Mailgun-compatible IP Pool API lets software that was written for Mailgun’s dedicated IP pool API read and create GreenArrow Routes. A Mailgun IP pool is a GreenArrow Route, and the IP addresses of a pool are the IP addresses of the Route. A Route that you create in another way (for example in the Engine UI or with the Routes API) is visible here.

GreenArrow assigns the IP addresses of a Route when it creates the Route. You cannot choose, add, remove, or move the IP addresses of a pool.

These endpoints are available:

Send each request to the hostname of the Mailgun compatibility API of your GreenArrow CloudMTA. The examples on this page use mg.api.example.com.

The Routes feature must be enabled on the GreenArrow installation. When it is not enabled, each endpoint on this page answers 404 with the message IP pools are not enabled on this GreenArrow installation.

Authentication

Authenticate with HTTP Basic authentication. The username is api, and the password is a GreenArrow API key.

curl -s --user "api:$API_KEY" "https://mg.api.example.com/v3/ip_pools"

A request with no credentials, with a username other than api, or with a key that is not valid gets a 401 response. Do not depend on the body of a 401 response; it can change in a later release.

Requests and Responses

Parameters

A parameter that this page does not list is ignored, as on Mailgun, in the query string and in the body. The exception is ips, which Create an IP Pool refuses.

An endpoint that takes form parameters reads them only from a multipart/form-data body, as Mailgun documents. These rules apply:

• A body of another content type (for example JSON, application/x-www-form-urlencoded, or no body) gets a 400. Mailgun accepts some of these bodies.
• A form parameter in the query string gets a 400. So does a form parameter that is sent as a file part.
• A value that has a NUL character, or that is not valid UTF-8, gets a 400.
• A body that is larger than 1 MiB (1,048,576 bytes, with the multipart framing) gets a 400. A body that is larger than 32 MiB can get a 502 with an HTML body.
• A parameter that is sent more than once gives its first value, as on Mailgun.

Errors

An error response has a JSON body, except the plain-text 404 for a path that is not a path of the Mailgun API, and the 502 for a body that is larger than 32 MiB. Most error bodies have one field, message:

{"message": "IP pools are not enabled on this GreenArrow installation"}

A 401 for a request that has no credentials that can be read has another body, as on Mailgun:

{"Error": "unauthorized"}

Use the status code to handle an error. Do not depend on the text of a message.

Common Fields

These are the fields of a pool in the responses on this page.

Get a List of IP Pools

Returns every IP pool. This is every Route that is not deleted.

GET /v3/ip_pools

Mailgun’s documentation: Get DIPPs.

Parameters

None.

Response

Example

curl -s --user "api:$API_KEY" "https://mg.api.example.com/v3/ip_pools"

200 OK:

{
  "ip_pools": [
    {
      "pool_id": "387cb3220000000000000007",
      "name": "transactional",
      "description": "Transactional mail",
      "ips": ["203.0.113.10"],
      "metadata": {},
      "is_linked": true,
      "is_inherited": false
    }
  ],
  "message": "success"
}

Create an IP Pool

Creates a Route with the name and the description. GreenArrow assigns the Route one IP address before it answers. The answer comes after the Route is ready to use.

POST /v3/ip_pools

Mailgun’s documentation: Create a DIPP.

Form Parameters

Send these parameters in a multipart/form-data body (see Requests and Responses).

GreenArrow also refuses ips, which Mailgun does not document, with the message ips is not supported: GreenArrow provisions pool addresses automatically.

When the name and the description both break a rule, the message has both messages, joined with ; .

Response

Errors

If a create gets a 500, check the pool list before retrying. The Route may have been created even if its response was lost.

Example

curl -s --user "api:$API_KEY" -X POST "https://mg.api.example.com/v3/ip_pools" \
  -F name=transactional \
  -F 'description=Transactional mail'

200 OK:

{"message": "success", "pool_id": "387cb3220000000000000007"}

400 Bad Request when the request has ip:

{"message": "ip is not supported: GreenArrow provisions pool addresses automatically"}

Identifiers

A pool_id is 24 hexadecimal characters, as on Mailgun. GreenArrow makes it from the id of the Route: the first 8 characters are always 387cb322, and the last 16 characters are the id of the Route in hexadecimal. For example, Route 7 is the pool 387cb3220000000000000007.

To send a message through a pool, give its pool_id as o:sending-ip-pool to the Mailgun-Compatible Messages API.

Differences from Mailgun

• The order of the list. GET /v3/ip_pools returns the pools in name order, with the letter case ignored. Mailgun’s list has no fixed order.
• metadata. Each pool in the list has "metadata": {}. Mailgun gives metadata.assignments there.
• is_inherited. It is always false, because GreenArrow has no subaccounts.
• IP addresses. GreenArrow assigns the IP addresses of a pool when it creates the pool. You cannot add, remove, or move IP addresses. POST /v3/ip_pools refuses ip (and ips). A new Mailgun pool has no IP addresses; a new GreenArrow pool has one.
• Required parameters. POST /v3/ip_pools requires name and description. Mailgun accepts a request without them.
• Name rules. GreenArrow removes the spaces around a name, and refuses a blank name, a name of more than 180 characters, a name with other characters than ASCII 0x20 to 0x7e (or with a comma, #, or @), a name that is an integer, and the name of another pool. Mailgun has none of these rules.
• Description limit. A description has at most 10,240 characters. Mailgun accepted the tested longer descriptions.
• Request formats. The endpoints that take form parameters accept only a multipart/form-data body of at most 1 MiB, with the form parameters in the body. Mailgun also accepts other bodies, larger bodies, and form parameters in the query string or in a file part.
• Errors. The text of an error message can differ from Mailgun’s, and when a request has more than one problem, GreenArrow can report a different one than Mailgun.