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.
| Field | Required | Type | Description |
|---|---|---|---|
| name | yes | string | The name of the new pool |
| description | no | string | Description of the pool, for human use. |
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+AddressesTo 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:
| Field | Required | Type | Description |
|---|---|---|---|
| ip | yes | string | The name of the existing pool |
| name | yes | string | 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=sharedpool1This 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.1DELETE requests, like post requests, support both JSON and urlencoded formats.
