MENU navbar-image

Introduction

This documentation aims to provide all the information you need to work with our API.

As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Team Settings > API Tokens.

Domains

Retrieve Domains.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/domains?page=1&per_page=15" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/domains"
);

const params = {
    "page": "1",
    "per_page": "15",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/domains';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
            'per_page' => '15',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/domains'
params = {
  'page': '1',
  'per_page': '15',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "Domains retrieved successfully.",
    "data": [
        {
            "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
            "value": "example.com",
            "description": "Primary sending domain",
            "created_at": "2026-03-28T10:30:00.000000Z",
            "updated_at": "2026-03-28T10:30:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Request      

GET api/v1/domains

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

page   integer  optional    

The page number. Must be at least 1. Example: 1

per_page   integer  optional    

The number of domains per page. Must be at least 1. Must not be greater than 100. Example: 15

Retrieve Domain Feed.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed?page=1&date=2026-07-29" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed"
);

const params = {
    "page": "1",
    "date": "2026-07-29",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
            'date' => '2026-07-29',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed'
params = {
  'page': '1',
  'date': '2026-07-29',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "Domain feed retrieved successfully.",
    "data": [
        {
            "reported_at": "Mar 28, 2026 5:30PM",
            "mail_stream": "Transactional Stream",
            "domain": {
                "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "value": "example.com",
                "description": "Primary sending domain",
                "created_at": "2026-03-28T10:30:00.000000Z",
                "updated_at": "2026-03-28T10:30:00.000000Z"
            },
            "spf_domain": "example.com",
            "seed_message": {
                "mail_from_name": "Test Sender",
                "mail_from": "sender@example.com",
                "subject": "Seed message",
                "preview_line": "This is a preview.",
                "is_compliant": true,
                "is_blocklisted": false,
                "is_test": false
            }
        },
        {
            "message": "SPF is valid.",
            "reported_at": "Mar 28, 2026 4:45PM",
            "mail_stream": "Transactional Stream",
            "domain": {
                "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "value": "example.com",
                "description": "Primary sending domain",
                "created_at": "2026-03-28T10:30:00.000000Z",
                "updated_at": "2026-03-28T10:30:00.000000Z"
            },
            "spf_domain": null,
            "seed_message": null
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "per_page": 15,
        "to": 15,
        "total": 16
    }
}

Example response (403):


{
    "success": false,
    "message": "Feed is only available for activated domains.",
    "data": []
}

Request      

GET api/v1/domains/{id}/feed

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ULID of the domain. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Query Parameters

page   integer  optional    

The page number for paginated feed results. Must be at least 1. Example: 1

date   string  optional    

Filter feed items reported on or after this date, up to today. Must not be older than 90 days from today. Must be a valid date in the format Y-m-d. Example: 2026-07-29

Retrieve Domain.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV?start_date=2026-01-01&end_date=2026-03-31&related_ips_page=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"related_ips_page\": 16,
    \"start_date\": \"2022-08-23\",
    \"end_date\": \"2052-08-21\"
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV"
);

const params = {
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "related_ips_page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "related_ips_page": 16,
    "start_date": "2022-08-23",
    "end_date": "2052-08-21"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'start_date' => '2026-01-01',
            'end_date' => '2026-03-31',
            'related_ips_page' => '1',
        ],
        'json' => [
            'related_ips_page' => 16,
            'start_date' => '2022-08-23',
            'end_date' => '2052-08-21',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/domains/01ARZ3NDEKTSV4RRFFQ69G5FAV'
payload = {
    "related_ips_page": 16,
    "start_date": "2022-08-23",
    "end_date": "2052-08-21"
}
params = {
  'start_date': '2026-01-01',
  'end_date': '2026-03-31',
  'related_ips_page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "Domain retrieved successfully.",
    "data": {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "value": "example.com",
        "description": "Primary sending domain",
        "created_at": "2026-03-28T10:30:00.000000Z",
        "updated_at": "2026-03-28T10:30:00.000000Z",
        "logo": null,
        "team": {
            "name": "Owner Custom Team"
        },
        "mail_streams": [
            {
                "name": "Transactional Stream",
                "type": "transactional",
                "logo": "https://cdn.example.com/mail-streams/transactional.svg"
            }
        ],
        "configuration": {
            "spf_domains": [],
            "dkim_selectors": [],
            "bimi_selectors": [],
            "dmarc": {
                "valid": true,
                "record": "v=DMARC1; p=none;"
            },
            "mx": {
                "valid": true,
                "records": [
                    "mx1.example.com",
                    "mx2.example.com"
                ]
            },
            "created_at": "2026-03-28T10:30:00.000000Z",
            "updated_at": "2026-03-28T10:30:00.000000Z"
        },
        "alignment": {
            "items": []
        },
        "settings": {
            "estimated_message_volume": "1000",
            "general_settings": {
                "estimated_message_volume": "1000"
            },
            "shared_team_ids": [],
            "mail_streams": [
                {
                    "name": "Transactional Stream",
                    "type": "transactional",
                    "general_settings": []
                }
            ],
            "spf_domains": []
        },
        "compliance": {
            "is_compliant": true,
            "pre_send": {
                "is_compliant": true,
                "mail_streams": [
                    {
                        "name": "Transactional Stream",
                        "type": "transactional",
                        "is_compliant": true,
                        "checks": {
                            "ips": true,
                            "one_click_unsub": false,
                            "blocklists": true,
                            "spf": true,
                            "dkim": true,
                            "dmarc": true,
                            "tls": true
                        }
                    }
                ]
            },
            "post_send": {
                "is_compliant": false,
                "requirements": {
                    "spf": true,
                    "dkim": null,
                    "dmarc_alignment": null,
                    "dmarc_policy": false,
                    "encryption": null,
                    "user_reported_spam_rate": null,
                    "dns_records": null,
                    "one_click_unsubscribe": null,
                    "honor_unsubscribe": null,
                    "message_formatting": null
                },
                "subdomain": {
                    "domain_id": "mail.example.com",
                    "requirements": {
                        "spf": false,
                        "dkim": false,
                        "dmarc_alignment": null,
                        "dmarc_policy": null,
                        "encryption": null,
                        "user_reported_spam_rate": null,
                        "dns_records": null,
                        "one_click_unsubscribe": null,
                        "honor_unsubscribe": null,
                        "message_formatting": null
                    }
                }
            },
            "mail_streams": [
                {
                    "name": "Transactional Stream",
                    "type": "transactional",
                    "is_compliant": true,
                    "checks": {
                        "ips": true,
                        "one_click_unsub": false,
                        "blocklists": true,
                        "spf": true,
                        "dkim": true,
                        "dmarc": true,
                        "tls": true
                    }
                }
            ]
        },
        "complaint_rate_averages": {
            "periods": []
        },
        "related_ips": {
            "date_range": {
                "start_date": "2026-01-01 00:00:00",
                "end_date": "2026-03-31 23:59:59"
            },
            "items": [
                {
                    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                    "value": "192.0.2.10",
                    "description": "Primary sending IP",
                    "created_at": "2026-03-28T10:30:00.000000Z",
                    "updated_at": "2026-03-28T10:30:00.000000Z"
                }
            ],
            "meta": {
                "current_page": 1,
                "last_page": 1,
                "per_page": 10,
                "total": 0
            }
        },
        "blocklists": {
            "is_blacklist": false,
            "blacklist_count": 0,
            "listed_count": 0,
            "listed_muted": 0,
            "listed_details": []
        }
    }
}

Request      

GET api/v1/domains/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ULID of the domain. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Query Parameters

start_date   string  optional    

Filter related IPs from this date (Y-m-d). Maximum selected range is 90 days. Example: 2026-01-01

end_date   string  optional    

Filter related IPs until this date (Y-m-d). Maximum selected range is 90 days. Example: 2026-03-31

related_ips_page   integer  optional    

The page number for related IP results. Example: 1

Body Parameters

related_ips_page   integer  optional    

Must be at least 1. Example: 16

start_date   string  optional    

Must be a valid date in the format Y-m-d. Must be a date before or equal to today. Must be a date before or equal to end_date. Example: 2022-08-23

end_date   string  optional    

Must be a valid date in the format Y-m-d. Must be a date before or equal to today. Must be a date after or equal to start_date. Example: 2052-08-21

IPs

Retrieve IPs.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/ips?page=1&per_page=15" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/ips"
);

const params = {
    "page": "1",
    "per_page": "15",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/ips';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
            'per_page' => '15',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/ips'
params = {
  'page': '1',
  'per_page': '15',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "IPs retrieved successfully.",
    "data": [
        {
            "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
            "value": "192.0.2.10",
            "description": "Primary sending IP",
            "created_at": "2026-03-28T10:30:00.000000Z",
            "updated_at": "2026-03-28T10:30:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Request      

GET api/v1/ips

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

page   integer  optional    

The page number. Must be at least 1. Example: 1

per_page   integer  optional    

The number of IPs per page. Must be at least 1. Must not be greater than 100. Example: 15

Retrieve IP Feed.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed?page=1&date=2026-07-29" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed"
);

const params = {
    "page": "1",
    "date": "2026-07-29",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
            'date' => '2026-07-29',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV/feed'
params = {
  'page': '1',
  'date': '2026-07-29',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "IP feed retrieved successfully.",
    "data": [
        {
            "reported_at": "Mar 28, 2026 5:30PM",
            "mail_stream": "Transactional Stream",
            "ip": {
                "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "value": "192.0.2.10",
                "description": "Primary sending IP",
                "created_at": "2026-03-28T10:30:00.000000Z",
                "updated_at": "2026-03-28T10:30:00.000000Z"
            },
            "seed_message": {
                "mail_from_name": "Test Sender",
                "mail_from": "sender@example.com",
                "subject": "Seed message",
                "preview_line": "This is a preview.",
                "is_compliant": true,
                "is_blocklisted": false,
                "is_test": false
            }
        },
        {
            "message": "IP is compliant.",
            "reported_at": "Mar 28, 2026 4:45PM",
            "mail_stream": "Transactional Stream",
            "ip": {
                "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "value": "192.0.2.10",
                "description": "Primary sending IP",
                "created_at": "2026-03-28T10:30:00.000000Z",
                "updated_at": "2026-03-28T10:30:00.000000Z"
            },
            "seed_message": null
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "per_page": 15,
        "to": 15,
        "total": 16
    }
}

Example response (403):


{
    "success": false,
    "message": "Feed is only available for activated IPs.",
    "data": []
}

Request      

GET api/v1/ips/{id}/feed

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ULID of the IP. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Query Parameters

page   integer  optional    

The page number for paginated feed results. Must be at least 1. Example: 1

date   string  optional    

Filter feed items reported on or after this date, up to today. Must not be older than 90 days from today. Must be a valid date in the format Y-m-d. Example: 2026-07-29

Retrieve IP.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV?start_date=2026-01-01&end_date=2026-03-31&related_domains_page=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"related_domains_page\": 16,
    \"start_date\": \"2022-08-23\",
    \"end_date\": \"2052-08-21\"
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV"
);

const params = {
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "related_domains_page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "related_domains_page": 16,
    "start_date": "2022-08-23",
    "end_date": "2052-08-21"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'start_date' => '2026-01-01',
            'end_date' => '2026-03-31',
            'related_domains_page' => '1',
        ],
        'json' => [
            'related_domains_page' => 16,
            'start_date' => '2022-08-23',
            'end_date' => '2052-08-21',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/ips/01ARZ3NDEKTSV4RRFFQ69G5FAV'
payload = {
    "related_domains_page": 16,
    "start_date": "2022-08-23",
    "end_date": "2052-08-21"
}
params = {
  'start_date': '2026-01-01',
  'end_date': '2026-03-31',
  'related_domains_page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "IP retrieved successfully.",
    "data": {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "value": "192.0.2.10",
        "description": "Primary sending IP",
        "created_at": "2026-03-28T10:30:00.000000Z",
        "updated_at": "2026-03-28T10:30:00.000000Z",
        "logo": null,
        "team": {
            "name": "Owner Custom Team"
        },
        "mail_streams": [
            {
                "name": "Transactional Stream",
                "type": "transactional",
                "logo": "https://cdn.example.com/mail-streams/transactional.svg"
            }
        ],
        "configuration": {
            "rdns": "mail.example.com",
            "fcrdns": true,
            "rdns_summary": null,
            "provider": {
                "asn": {
                    "asn": "AS64500",
                    "name": "Example ASN"
                },
                "location": "37.7749,-122.4194"
            },
            "created_at": "2026-03-28T10:30:00.000000Z",
            "updated_at": "2026-03-28T10:30:00.000000Z"
        },
        "settings": {
            "shared_team_ids": []
        },
        "compliance": {
            "is_compliant": true,
            "sender_score": 98,
            "checks": {
                "blocklists": true,
                "fcrdns": true
            }
        },
        "complaint_rate_averages": {
            "periods": []
        },
        "inbox_placement_averages": {
            "periods": []
        },
        "related_domains": {
            "date_range": {
                "start_date": "2026-01-01 00:00:00",
                "end_date": "2026-03-31 23:59:59"
            },
            "items": [
                {
                    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                    "value": "example.com",
                    "description": "Primary sending domain",
                    "created_at": "2026-03-28T10:30:00.000000Z",
                    "updated_at": "2026-03-28T10:30:00.000000Z"
                }
            ],
            "meta": {
                "current_page": 1,
                "last_page": 1,
                "per_page": 10,
                "total": 0
            }
        },
        "blocklists": {
            "is_blacklist": false,
            "blacklist_count": 0,
            "listed_count": 0,
            "listed_muted": 0,
            "listed_details": []
        }
    }
}

Request      

GET api/v1/ips/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ULID of the IP. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Query Parameters

start_date   string  optional    

Filter related domains from this date (Y-m-d). Maximum selected range is 90 days. Example: 2026-01-01

end_date   string  optional    

Filter related domains until this date (Y-m-d). Maximum selected range is 90 days. Example: 2026-03-31

related_domains_page   integer  optional    

The page number for related domain results. Example: 1

Body Parameters

related_domains_page   integer  optional    

Must be at least 1. Example: 16

start_date   string  optional    

Must be a valid date in the format Y-m-d. Must be a date before or equal to today. Must be a date before or equal to end_date. Example: 2022-08-23

end_date   string  optional    

Must be a valid date in the format Y-m-d. Must be a date before or equal to today. Must be a date after or equal to start_date. Example: 2052-08-21

Intelligence

Single Email

Retrieve Single Email.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": {
        "id": 27,
        "email": "price.amber@example.org",
        "status": null,
        "created_at": "2026-07-29 17:26:20",
        "updated_at": "2026-07-29 17:26:20"
    }
}

Request      

GET api/v1/intelligence/single-emails/{email}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

email   string     

The email address to retrieve. Example: example@postmasterplus.com

Scan Single Email.

requires authentication

Example request:
curl --request POST \
    "https://postmasterplus.app/api/v1/intelligence/single-emails/scan" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"example@postmasterplus.com\",
    \"actions\": \"\\\"verification,activity,postal_append\\\"\"
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/intelligence/single-emails/scan"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "example@postmasterplus.com",
    "actions": "\"verification,activity,postal_append\""
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/intelligence/single-emails/scan';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'email' => 'example@postmasterplus.com',
            'actions' => '"verification,activity,postal_append"',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/intelligence/single-emails/scan'
payload = {
    "email": "example@postmasterplus.com",
    "actions": "\"verification,activity,postal_append\""
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": 28,
        "email": "rempel.chadrick@example.org",
        "status": null,
        "created_at": "2026-07-29 17:26:20",
        "updated_at": "2026-07-29 17:26:20"
    }
}

Request      

POST api/v1/intelligence/single-emails/scan

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

email   string     

The email address to scan. Example: example@postmasterplus.com

actions   string     

The actions in comma separated format to perform. Example: "verification,activity,postal_append"

Delete Single Email.

requires authentication

Example request:
curl --request DELETE \
    "https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/intelligence/single-emails/example@postmasterplus.com'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

Example response (200):


{
    "message": "Single email deleted.",
    "deleted": true
}

Request      

DELETE api/v1/intelligence/single-emails/{email}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

email   string     

The email address to delete. Example: example@postmasterplus.com

Blocklists

Blocklist Scan

Start Blocklist Scan.

requires authentication

Example request:
curl --request POST \
    "https://postmasterplus.app/api/v1/blocklist/scan/start" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"urls\": [
        \"https:\\/\\/optipub.com\\/newsletter\",
        \"optipub.com\",
        \"8.8.8.8\"
    ],
    \"follow_redirects\": true
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/blocklist/scan/start"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "urls": [
        "https:\/\/optipub.com\/newsletter",
        "optipub.com",
        "8.8.8.8"
    ],
    "follow_redirects": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/blocklist/scan/start';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'urls' => ['https://optipub.com/newsletter', 'optipub.com', '8.8.8.8'],
            'follow_redirects' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/blocklist/scan/start'
payload = {
    "urls": [
        "https:\/\/optipub.com\/newsletter",
        "optipub.com",
        "8.8.8.8"
    ],
    "follow_redirects": true
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "01kyqekeet8me0d3j3zsmwpjjq",
        "status": "pending",
        "status_label": "Pending",
        "unique_hosts_checked": 3,
        "total_hosts_detected": null,
        "urls_scanned": 0,
        "urls_skipped": 0,
        "blocklisted": false,
        "credits_used": 0,
        "error_message": "",
        "started_at": null,
        "completed_at": null
    },
    "success": true,
    "message": "Blocklist check started successfully."
}

Request      

POST api/v1/blocklist/scan/start

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

urls   string[]     

Array of HTTP(S) URLs, bare domains, or public IP addresses to scan (minimum 1 target, maximum 100 targets).
*   string     

Valid HTTP(S) URL, bare domain, or public IPv4/IPv6 address (maximum 10000 characters). Example: "optipub.com"

follow_redirects   boolean  optional    

optional Whether to follow redirects for full HTTP(S) URL targets. Defaults to true. Bare domains and IP targets always bypass redirect processing. Example: true

Response

Response Fields

data   object     
id   string     

The unique identifier for the blocklist check.

status   string     

The status of the blocklist check. Example: pending, processing, completed, partially_completed, failed

Must be one of:
  • pending
  • processing
  • completed
  • partially_completed
  • failed
status_label   string     

Human-friendly status label. Example: Pending, Processing, Completed, Partially Completed, Failed

unique_hosts_checked   integer     

The number of unique hosts checked.

total_hosts_detected   integer     

The number of hosts detected.

urls_scanned   integer     

The number of URLs scanned.

urls_skipped   integer     

The number of URLs skipped.

blocklisted   boolean     

Whether the check is blocklisted.

credits_used   integer     

The number of credits used.

error_message   string     

The error message if the check failed.

started_at   string     

The date and time the check started.

completed_at   string     

The date and time the check completed.

results   object     

Detailed results of the blocklist check. Only included when the check is completed and results are requested. Contains a data array with monitoring history items.
data   string[]     

Array of blacklist monitoring history items, each containing URL, redirect information, and blocklist status for each host checked.
url   string     

The URL that was checked for blocklist status.

total_redirects   integer     

Total number of redirects found for this URL.

redirect_urls   string[]     

Array of redirect URLs encountered during the check.

hosts_checked   string[]     

Array of hosts that were checked for blocklist status.
host   string     

The hostname that was checked.

position   integer     

The position of this host in the redirect chain.

blocklisted   boolean     

Whether this host is blocklisted.

listed_details   string[]     

Array of blocklist details for this host.
host   string     

The blocklist hostname.

name   string     

The name of the blocklist.

listed   boolean     

Whether the host is listed on this blocklist.

details   string     

Additional details about the blocklist status.

Retrieve Blocklist Scan Status.

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/blocklist/scan/status/01ARZ3NDEKTSV4RRFFQ69G5FAV" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/blocklist/scan/status/01ARZ3NDEKTSV4RRFFQ69G5FAV"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/blocklist/scan/status/01ARZ3NDEKTSV4RRFFQ69G5FAV';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/blocklist/scan/status/01ARZ3NDEKTSV4RRFFQ69G5FAV'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": {
        "id": "01kyqekefbyc35ftbcz3pq2gh7",
        "status": "pending",
        "status_label": "Pending",
        "unique_hosts_checked": 4,
        "total_hosts_detected": null,
        "urls_scanned": 0,
        "urls_skipped": 0,
        "blocklisted": false,
        "credits_used": 0,
        "error_message": "",
        "started_at": null,
        "completed_at": null
    },
    "success": true,
    "message": "Blocklist check status retrieved successfully."
}

Request      

GET api/v1/blocklist/scan/status/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ULID of the blocklist check. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Response

Response Fields

data   object     
id   string     

The unique identifier for the blocklist check.

status   string     

The status of the blocklist check. Example: pending, processing, completed, partially_completed, failed

Must be one of:
  • pending
  • processing
  • completed
  • partially_completed
  • failed
status_label   string     

Human-friendly status label. Example: Pending, Processing, Completed, Partially Completed, Failed

unique_hosts_checked   integer     

The number of unique hosts checked.

total_hosts_detected   integer     

The number of hosts detected.

urls_scanned   integer     

The number of URLs scanned.

urls_skipped   integer     

The number of URLs skipped.

blocklisted   boolean     

Whether the check is blocklisted.

credits_used   integer     

The number of credits used.

error_message   string     

The error message if the check failed.

started_at   string     

The date and time the check started.

completed_at   string     

The date and time the check completed.

results   object     

Detailed results of the blocklist check. Only included when the check is completed and results are requested. Contains a data array with monitoring history items.
data   string[]     

Array of blacklist monitoring history items, each containing URL, redirect information, and blocklist status for each host checked.
url   string     

The URL that was checked for blocklist status.

total_redirects   integer     

Total number of redirects found for this URL.

redirect_urls   string[]     

Array of redirect URLs encountered during the check.

hosts_checked   string[]     

Array of hosts that were checked for blocklist status.
host   string     

The hostname that was checked.

position   integer     

The position of this host in the redirect chain.

blocklisted   boolean     

Whether this host is blocklisted.

listed_details   string[]     

Array of blocklist details for this host.
host   string     

The blocklist hostname.

name   string     

The name of the blocklist.

listed   boolean     

Whether the host is listed on this blocklist.

details   string     

Additional details about the blocklist status.

Seedbox

GET api/v1/seedboxes

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/seedboxes" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"status\": \"active\",
    \"client_reference\": \"b\",
    \"per_page\": 22,
    \"page\": 67
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "status": "active",
    "client_reference": "b",
    "per_page": 22,
    "page": 67
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'status' => 'active',
            'client_reference' => 'b',
            'per_page' => 22,
            'page' => 67,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes'
payload = {
    "status": "active",
    "client_reference": "b",
    "per_page": 22,
    "page": 67
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Request      

GET api/v1/seedboxes

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

status   string  optional    

Example: active

Must be one of:
  • active
  • revoked
mode   string  optional    
client_reference   string  optional    

Must not be greater than 255 characters. Example: b

per_page   integer  optional    

Must be at least 1. Must not be greater than 100. Example: 22

page   integer  optional    

Must be at least 1. Example: 67

POST api/v1/seedboxes

requires authentication

Example request:
curl --request POST \
    "https://postmasterplus.app/api/v1/seedboxes" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"b\",
    \"client_reference\": \"n\",
    \"scan_blocklists\": false
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "b",
    "client_reference": "n",
    "scan_blocklists": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'b',
            'client_reference' => 'n',
            'scan_blocklists' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes'
payload = {
    "name": "b",
    "client_reference": "n",
    "scan_blocklists": false
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Request      

POST api/v1/seedboxes

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

name   string     

Must not be greater than 120 characters. Example: b

client_reference   string  optional    

Must not be greater than 255 characters. Example: n

scan_blocklists   boolean  optional    

Example: false

mode   string  optional    
max_messages   string  optional    
expires_at   string  optional    

GET api/v1/seedboxes/{seedbox}/messages

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 1,
    \"page\": 22,
    \"include_content\": \"1\"
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "per_page": 1,
    "page": 22,
    "include_content": "1"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'per_page' => 1,
            'page' => 22,
            'include_content' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages'
payload = {
    "per_page": 1,
    "page": 22,
    "include_content": "1"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Request      

GET api/v1/seedboxes/{seedbox}/messages

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   string     

The seedbox. Example: 58C6f7nnFCJ9M6rjyc6rTKMzn6

Body Parameters

per_page   integer  optional    

Must be at least 1. Must not be greater than 100. Example: 1

page   integer  optional    

Must be at least 1. Example: 22

include_content   string  optional    

Example: 1

Must be one of:
  • true
  • false
  • 1
  • 0

GET api/v1/seedboxes/{seedbox}/messages/{message}

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"include_content\": \"false\"
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "include_content": "false"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'include_content' => 'false',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc'
payload = {
    "include_content": "false"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Request      

GET api/v1/seedboxes/{seedbox}/messages/{message}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   string     

The seedbox. Example: 58C6f7nnFCJ9M6rjyc6rTKMzn6

message   string     

The message. Example: BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc

Body Parameters

include_content   string  optional    

Example: false

Must be one of:
  • true
  • false
  • 1
  • 0

Request a one-click unsubscribe for the list behind a seedbox message.

requires authentication

Mirrors the web endpoint exactly: this action owns no unsubscribe logic of its own, it resolves the message through the current team, delegates to the shared action, and maps the returned outcome to a status through {@see RequestUnsubscribeOutcome}, so every surface agrees on whether an outcome counts as a success. A rate_limited outcome answers 429 and the same request may succeed once the budget refills.

Example request:
curl --request POST \
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc/unsubscribe" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc/unsubscribe"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc/unsubscribe';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/messages/BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc/unsubscribe'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers)
response.json()

Request      

POST api/v1/seedboxes/{seedbox}/messages/{message}/unsubscribe

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   string     

The seedbox. Example: 58C6f7nnFCJ9M6rjyc6rTKMzn6

message   string     

The message. Example: BcECdBDA-CdED-bFEA-CbCE-BcCdeBfbbebc

GET api/v1/seedboxes/{seedbox_id}/subscriptions

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/seedboxes/architecto/subscriptions" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"state\": \"unsubscribe_failed\",
    \"search\": \"b\",
    \"sort\": \"oldest_seen_at\",
    \"per_page\": 22,
    \"page\": 67
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/architecto/subscriptions"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "state": "unsubscribe_failed",
    "search": "b",
    "sort": "oldest_seen_at",
    "per_page": 22,
    "page": 67
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/architecto/subscriptions';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'state' => 'unsubscribe_failed',
            'search' => 'b',
            'sort' => 'oldest_seen_at',
            'per_page' => 22,
            'page' => 67,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/architecto/subscriptions'
payload = {
    "state": "unsubscribe_failed",
    "search": "b",
    "sort": "oldest_seen_at",
    "per_page": 22,
    "page": 67
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Request      

GET api/v1/seedboxes/{seedbox_id}/subscriptions

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox_id   string     

The ID of the seedbox. Example: architecto

Body Parameters

state   string  optional    

Example: unsubscribe_failed

Must be one of:
  • subscribed
  • unsubscribe_pending
  • unsubscribe_failed
  • unsubscribed
  • mail_after_unsubscribe_within_threshold
  • mail_after_unsubscribe
search   string  optional    

Must not be greater than 255 characters. Example: b

sort   string  optional    

Example: oldest_seen_at

Must be one of:
  • severity
  • last_seen_at
  • oldest_seen_at
per_page   integer  optional    

Must be at least 1. Must not be greater than 100. Example: 22

page   integer  optional    

Must be at least 1. Example: 67

Request an unsubscribe from every actionable list matching the given filters.

requires authentication

Requests are paced, so this answers 202 with counts rather than a per-list outcome.

Example request:
curl --request POST \
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/unsubscribe-all" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"state\": \"mail_after_unsubscribe_within_threshold\",
    \"search\": \"b\",
    \"sort\": \"oldest_seen_at\"
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/unsubscribe-all"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "state": "mail_after_unsubscribe_within_threshold",
    "search": "b",
    "sort": "oldest_seen_at"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/unsubscribe-all';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'state' => 'mail_after_unsubscribe_within_threshold',
            'search' => 'b',
            'sort' => 'oldest_seen_at',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/unsubscribe-all'
payload = {
    "state": "mail_after_unsubscribe_within_threshold",
    "search": "b",
    "sort": "oldest_seen_at"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Request      

POST api/v1/seedboxes/{seedbox}/subscriptions/unsubscribe-all

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   string     

The seedbox. Example: 58C6f7nnFCJ9M6rjyc6rTKMzn6

Body Parameters

state   string  optional    

Example: mail_after_unsubscribe_within_threshold

Must be one of:
  • subscribed
  • unsubscribe_pending
  • unsubscribe_failed
  • unsubscribed
  • mail_after_unsubscribe_within_threshold
  • mail_after_unsubscribe
search   string  optional    

Must not be greater than 255 characters. Example: b

sort   string  optional    

Example: oldest_seen_at

Must be one of:
  • severity
  • last_seen_at
  • oldest_seen_at

POST api/v1/seedboxes/{seedbox}/subscriptions/{subscription}/unsubscribe

requires authentication

Example request:
curl --request POST \
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/564/unsubscribe" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/564/unsubscribe"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/564/unsubscribe';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6/subscriptions/564/unsubscribe'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers)
response.json()

Request      

POST api/v1/seedboxes/{seedbox}/subscriptions/{subscription}/unsubscribe

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   string     

The seedbox. Example: 58C6f7nnFCJ9M6rjyc6rTKMzn6

subscription   string     

The subscription. Example: 564

GET api/v1/seedboxes/{seedbox}

requires authentication

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Request      

GET api/v1/seedboxes/{seedbox}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   string     

The seedbox. Example: 58C6f7nnFCJ9M6rjyc6rTKMzn6

Update editable seedbox metadata without changing its address or lifecycle.

requires authentication

Example request:
curl --request PATCH \
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Transactional seedbox\",
    \"client_reference\": \"campaign-2026-07\",
    \"scan_blocklists\": true
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Transactional seedbox",
    "client_reference": "campaign-2026-07",
    "scan_blocklists": true
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6';
$response = $client->patch(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Transactional seedbox',
            'client_reference' => 'campaign-2026-07',
            'scan_blocklists' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58C6f7nnFCJ9M6rjyc6rTKMzn6'
payload = {
    "name": "Transactional seedbox",
    "client_reference": "campaign-2026-07",
    "scan_blocklists": true
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PATCH', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "01kyqekejn58n2kmn1d4tf9c3t",
        "team_id": 351,
        "name": null,
        "client_reference": null,
        "status": "active",
        "address": "ac141390ef87d2ce718fa457d3ef2322@b-01kyqekejn58n2kmn1d4tf9c3v.seeds.dev.optipub.com",
        "scan_blocklists": false,
        "receive_credits_per_message": 1,
        "messages_count": 0,
        "rejected_insufficient_credit_count": 0,
        "unresolved_insufficient_credit_rejection_count": 0,
        "accepting_messages": true,
        "can_delete": false,
        "revoked_at": null,
        "last_received_at": null,
        "last_rejected_insufficient_credit_at": null,
        "created_at": "2026-07-29T17:26:21+00:00"
    },
    "success": true,
    "message": "Seedbox updated successfully."
}

Request      

PATCH api/v1/seedboxes/{seedbox}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   string     

The seedbox. Example: 58C6f7nnFCJ9M6rjyc6rTKMzn6

Body Parameters

name   string  optional    

A non-empty human-readable name. Omit this field to preserve the current name. Must not be greater than 120 characters. Example: Transactional seedbox

client_reference   string  optional    

A stable external identifier. Send null to clear it, or omit this field to preserve it. Must not be greater than 255 characters. Example: campaign-2026-07

scan_blocklists   boolean  optional    

Whether future received messages should be scanned against blocklists. Enabling it requires blocklist-check:scan:start and may increase future credit usage. Example: true

DELETE api/v1/seedboxes/{seedbox}

requires authentication

Example request:
curl --request DELETE \
    "https://postmasterplus.app/api/v1/seedboxes/58" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

Request      

DELETE api/v1/seedboxes/{seedbox}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   integer     

The seedbox. Example: 58

DELETE api/v1/seedboxes/{seedbox}/delete

requires authentication

Example request:
curl --request DELETE \
    "https://postmasterplus.app/api/v1/seedboxes/58/delete" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/seedboxes/58/delete"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/seedboxes/58/delete';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/seedboxes/58/delete'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

Request      

DELETE api/v1/seedboxes/{seedbox}/delete

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

seedbox   integer     

The seedbox. Example: 58

Spam Identifiers

Retrieve Spam Identifiers.

requires authentication

List all Gmail Postmaster Tools v2 spam (feedback loop) identifiers reported for accessible domains in the given date range, along with each identifier's average complaint rate across that window.

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/spam-identifiers?domain_id=01ARZ3NDEKTSV4RRFFQ69G5FAV&page=1&start_date=2026-01-22&end_date=2026-04-22" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/spam-identifiers"
);

const params = {
    "domain_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "page": "1",
    "start_date": "2026-01-22",
    "end_date": "2026-04-22",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/spam-identifiers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'domain_id' => '01ARZ3NDEKTSV4RRFFQ69G5FAV',
            'page' => '1',
            'start_date' => '2026-01-22',
            'end_date' => '2026-04-22',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/spam-identifiers'
params = {
  'domain_id': '01ARZ3NDEKTSV4RRFFQ69G5FAV',
  'page': '1',
  'start_date': '2026-01-22',
  'end_date': '2026-04-22',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "Spam identifiers retrieved successfully.",
    "data": [
        {
            "domain": {
                "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "value": "example.com"
            },
            "identifier": "66189376",
            "sample_count": 57,
            "average_complaint_rate": 0.12,
            "min_complaint_rate": 0.05,
            "max_complaint_rate": 0.31
        },
        {
            "domain": {
                "id": "01ARZ3NDEKTSV4RRFFQ69G5FBG",
                "value": "example.net"
            },
            "identifier": "66189799",
            "sample_count": 40,
            "average_complaint_rate": 0.05,
            "min_complaint_rate": 0.01,
            "max_complaint_rate": 0.14
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 25,
        "total": 2
    }
}

Request      

GET api/v1/spam-identifiers

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

domain_id   string  optional    

Optionally filter identifiers to a single accessible domain ULID. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

page   integer  optional    

The page number for paginated identifier results. Example: 1

start_date   string  optional    

Filter identifiers from this date (Y-m-d). Maximum selected range is 90 days. Example: 2026-01-22

end_date   string  optional    

Filter identifiers until this date (Y-m-d). Maximum selected range is 90 days. Example: 2026-04-22

Retrieve Spam Identifier.

requires authentication

Return the daily Gmail complaint rate time series for a single spam (feedback loop) identifier across accessible domains, plus the aggregate average over the selected date range for each domain.

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/spam-identifiers/66189376?domain_id=01ARZ3NDEKTSV4RRFFQ69G5FAV&start_date=2026-01-22&end_date=2026-04-22" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/spam-identifiers/66189376"
);

const params = {
    "domain_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "start_date": "2026-01-22",
    "end_date": "2026-04-22",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/spam-identifiers/66189376';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'domain_id' => '01ARZ3NDEKTSV4RRFFQ69G5FAV',
            'start_date' => '2026-01-22',
            'end_date' => '2026-04-22',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/spam-identifiers/66189376'
params = {
  'domain_id': '01ARZ3NDEKTSV4RRFFQ69G5FAV',
  'start_date': '2026-01-22',
  'end_date': '2026-04-22',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "Spam identifier retrieved successfully.",
    "data": [
        {
            "identifier": "66189376",
            "domain": {
                "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
                "value": "example.com"
            },
            "date_range": {
                "start_date": "2026-01-22",
                "end_date": "2026-04-22"
            },
            "aggregate": {
                "average_complaint_rate": 0.12,
                "sample_count": 57
            },
            "time_series": [
                {
                    "date": "2026-01-22",
                    "complaint_rate": 0.1
                },
                {
                    "date": "2026-01-23",
                    "complaint_rate": null
                }
            ]
        }
    ]
}

Example response (404):


{
    "success": false,
    "message": "Spam identifier not found for accessible domains in the selected date range.",
    "data": []
}

Request      

GET api/v1/spam-identifiers/{identifier}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

identifier   string     

The Gmail Postmaster Tools v2 spam (feedback loop) identifier. Example: 66189376

Query Parameters

domain_id   string  optional    

Optionally filter the identifier to a single accessible domain ULID. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

start_date   string  optional    

Start date of the reporting window (Y-m-d). Maximum selected range is 90 days. Example: 2026-01-22

end_date   string  optional    

End date of the reporting window (Y-m-d). Maximum selected range is 90 days. Example: 2026-04-22

Tools

Screenshot

Take Screenshot.

requires authentication

Take a screenshot of a URL or HTML content.

Example request:
curl --request POST \
    "https://postmasterplus.app/api/v1/screenshot/take" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"url\": \"\\\"https:\\/\\/example.com\\\"\",
    \"width\": 1280,
    \"height\": 720,
    \"format\": \"\\\"png\\\"\",
    \"device_scale\": 1
}"

const url = new URL(
    "https://postmasterplus.app/api/v1/screenshot/take"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "url": "\"https:\/\/example.com\"",
    "width": 1280,
    "height": 720,
    "format": "\"png\"",
    "device_scale": 1
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/screenshot/take';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'url' => '"https://example.com"',
            'width' => 1280,
            'height' => 720,
            'format' => '"png"',
            'device_scale' => 1,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/screenshot/take'
payload = {
    "url": "\"https:\/\/example.com\"",
    "width": 1280,
    "height": 720,
    "format": "\"png\"",
    "device_scale": 1
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "data": {
        "id": "01kyqekeg52k4bmaxvyp6x7g5b",
        "url": "https://assets.optipub.com/postmaster/screenshots/01kyqekefyzqag5hbbx98dt2qp/01kyqekeg52k4bmaxvyp6x7g5b.png",
        "format": "png",
        "width": 1024,
        "height": 600,
        "device_scale": 3,
        "credits_used": 1,
        "started_at": "2026-07-04T11:27:45+00:00",
        "completed_at": "2026-07-04T11:27:58+00:00",
        "created_at": "2026-07-29T17:26:20+00:00"
    },
    "success": true,
    "message": "Screenshot taken successfully."
}

Request      

POST api/v1/screenshot/take

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

url   string  optional    

URL to screenshot (required if html is not provided). Example: "https://example.com"

html   string  optional    

HTML content to screenshot (required if url is not provided).

width   integer  optional    

optional Viewport width in pixels (320-1920). Defaults to 1280. Example: 1280

height   integer  optional    

optional Viewport height in pixels (240-1080). Defaults to 720. Example: 720

format   string  optional    

optional Image format (png, jpeg, or webp). Defaults to png. Example: "png"

device_scale   integer  optional    

optional Device scale factor for higher resolution (1-3). Defaults to 1 for retina-quality images. Example: 1

Response

Response Fields

data   object     
id   string     

The unique identifier for the screenshot.

url   string     

The URL of the screenshot image.

format   string     

The format of the screenshot image. Example: png, jpeg

width   integer     

The width of the screenshot in pixels.

height   integer     

The height of the screenshot in pixels.

device_scale   integer     

The device scale factor used (1-3). Higher values produce sharper images.

credits_used   integer     

The number of credits used for this screenshot.

started_at   string     

The date and time when the screenshot capture started.

completed_at   string     

The date and time when the screenshot capture completed.

created_at   string     

The date and time the screenshot was created.

List Screenshots.

requires authentication

Retrieve a paginated list of screenshots for the current team.

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/screenshots?per_page=15&page=1&sort=-created_at" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/screenshots"
);

const params = {
    "per_page": "15",
    "page": "1",
    "sort": "-created_at",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/screenshots';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '15',
            'page' => '1',
            'sort' => '-created_at',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/screenshots'
params = {
  'per_page': '15',
  'page': '1',
  'sort': '-created_at',
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):


{
    "success": true,
    "message": "Screenshots retrieved successfully.",
    "data": [
        {
            "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
            "url": "https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png",
            "format": "png",
            "width": 1280,
            "height": 720,
            "credits_used": 1,
            "created_at": "2024-01-15T10:30:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 15,
        "to": 15,
        "total": 75
    }
}

Request      

GET api/v1/screenshots

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

The number of screenshots per page (1-100). Defaults to 15. Must be at least 1. Must not be greater than 100. Example: 15

page   integer  optional    

The page number. Must be at least 1. Example: 1

sort   string  optional    

Sort order. Use - prefix for descending. Options: created_at, -created_at, format, -format. Defaults to -created_at. Example: -created_at

Must be one of:
  • created_at
  • -created_at
  • format
  • -format

Get Screenshot.

requires authentication

Retrieve details of a specific screenshot by its ID.

Example request:
curl --request GET \
    --get "https://postmasterplus.app/api/v1/screenshot/01ARZ3NDEKTSV4RRFFQ69G5FAV" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://postmasterplus.app/api/v1/screenshot/01ARZ3NDEKTSV4RRFFQ69G5FAV"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://postmasterplus.app/api/v1/screenshot/01ARZ3NDEKTSV4RRFFQ69G5FAV';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://postmasterplus.app/api/v1/screenshot/01ARZ3NDEKTSV4RRFFQ69G5FAV'
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "data": {
        "id": "01kyqekegxmsngvqyn7djvv4vf",
        "url": "https://assets.optipub.com/postmaster/screenshots/01kyqekegqvdmrxcmytk25w8y0/01kyqekegxmsngvqyn7djvv4vf.png",
        "format": "png",
        "width": 800,
        "height": 600,
        "device_scale": 2,
        "credits_used": 1,
        "started_at": "2026-07-20T08:08:18+00:00",
        "completed_at": "2026-07-20T08:08:48+00:00",
        "created_at": "2026-07-29T17:26:20+00:00"
    },
    "success": true,
    "message": "Screenshot retrieved successfully."
}

Request      

GET api/v1/screenshot/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ULID of the screenshot. Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Response

Response Fields

data   object     
id   string     

The unique identifier for the screenshot.

url   string     

The URL of the screenshot image.

format   string     

The format of the screenshot image. Example: png, jpeg

width   integer     

The width of the screenshot in pixels.

height   integer     

The height of the screenshot in pixels.

device_scale   integer     

The device scale factor used (1-3). Higher values produce sharper images.

credits_used   integer     

The number of credits used for this screenshot.

started_at   string     

The date and time when the screenshot capture started.

completed_at   string     

The date and time when the screenshot capture completed.

created_at   string     

The date and time the screenshot was created.