REST API V1 Pools

MailerQ offers IP Pools for easy management of your sending IP addresses.

GET

A GET request to pools returns all pools. It returns a JSON array of pools, see the example below.

GET /v1/pools HTTP/1.0
Authorization: Bearer ...

Might result in

HTTP/1.0 200 Ok
Content-Type: application/json
...

[
    {
        "name": "sharedpool1"
    },
    {
        "name": "dedicated",
        "description": "Dedicated Addresses"
    }
]

In this example, there are 2 pools defined.

To get the actual IP addresses in a pool, you can do a GET request to poolips?name=NAME. The example below returns the IPs in pool "sharedpool1" from the example above.

GET /v1/poolips?name=sharedpool1 HTTP/1.0
Authorization: Bearer ...

This will return the list of IP addresses currently in the pool called NAME:

HTTP/1.0 200 Ok
Content-Type: application/json
...

[
    {
        "ip": "127.0.0.1",
        "name": "sharedpool1"
    },
    {
        "ip": "192.168.1.1",
        "name": "sharedpool1"
    }
]

POST

A POST request to pools allows you to create a new IP Pool. For the request format, see the table below.

For example, the request below will create the pool from the second example under GET with a json formatted body

POST /v1/pools HTTP/1.0
Content-Type: application/json
Authorization: Bearer ...

{
    "name": "dedicated",
    "description": "Dedicated Addresses"
}

and equivalently, with urlencoded body

POST /v1/pools HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer ...

name=dedicated&description=Dedicated+Addresses

To add an IP address to an existing pool, you can do a POST request to poolips. This needs the name of the pool and the address to be added:

POST /v1/poolips HTTP/1.0
Content-Type: application/json
Authorization: Bearer ...

{
    "ip": "127.0.0.1",
    "name": "sharedpool1"
},

Naturally, POST requests to poolips can also be done with urlencoded data.

DELETE

A DELETE request to pools allows you to remove a pool. This only needs the name of the pool to be removed:

DELETE /v1/pools HTTP/1.0
Authorization: Bearer ...
Content-Type: application/x-www-form-urlencoded

name=sharedpool1

This will also remove all addresses associated with that pool.

To remove a specific address from a pool, you can do a call to poolips with the name of the pool and the address you want to remove:

DELETE /v1/poolips HTTP/1.0
Authorization: Bearer ...
Content-Type: application/x-www-form-urlencoded

name=sharedpool1&ip=127.0.0.1

DELETE requests, like post requests, support both JSON and urlencoded formats.