Postmaster Accounts API

The Postmaster Accounts API provides access to Google Postmaster Tools data, including domain reputation, spam rates, IP reputation, authentication metrics, and delivery errors.

API access is available on Pro and Enterprise plans. You must first connect a Google Postmaster account in the InboxIssue dashboard under Postmaster Tools.

Connected Accounts

List your connected Google Postmaster accounts for the current workspace.

GET /api/v1/postmaster_accounts/connected

Response

{
  "connected_accounts": [
    {
      "id": 42,
      "email": "admin@yourcompany.com",
      "created_at": "2025-06-15T09:00:00Z"
    }
  ]
}

Error Response

404 — No connected accounts:

{
  "error": "No connected accounts found"
}

Get Cumulative Postmaster Data

Retrieve cumulative postmaster data across all domains for a connected account.

GET /api/v1/postmaster_accounts

Query Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Email address of the connected Google Postmaster account

Response

{
  "data": {
    "spam_rate": { ... },
    "ip_reputation": { ... },
    "domain_reputation": { ... },
    "feedback_loop": { ... },
    "authentication": { ... },
    "encryption": { ... },
    "delivery_errors": { ... }
  }
}

Error Responses

404 — No data available:

{
  "error": "No data available for the selected account."
}

Get Domain Postmaster Data

Retrieve detailed postmaster data for a specific domain with optional date filtering.

GET /api/v1/postmaster_accounts/:id

Path Parameters

Parameter	Type	Description
`id`	integer	Connected account ID (from the `/connected` endpoint)

Query Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Email of the connected Postmaster account
`item`	string	Yes	Domain to query (e.g., `yourcompany.com`)
`start_date`	string	No	Start date in `YYYY-MM-DD` format
`end_date`	string	No	End date in `YYYY-MM-DD` format

If you provide start_date, you must also provide end_date, and vice versa. Both must use YYYY-MM-DD format.

Response

{
  "spam_rate_data": [
    { "date": "2025-03-15", "value": 0.02 }
  ],
  "ip_reputation_data": [
    { "date": "2025-03-15", "high": 5, "medium": 2, "low": 1, "bad": 0 }
  ],
  "domain_reputation_data": [
    { "date": "2025-03-15", "reputation": "HIGH" }
  ],
  "feedback_loop_data": [
    { "date": "2025-03-15", "spam_count": 3, "fbl_count": 1 }
  ],
  "authentication_data": [
    { "date": "2025-03-15", "spf_success_ratio": 0.98, "dkim_success_ratio": 0.99, "dmarc_success_ratio": 0.97 }
  ],
  "encryption_data": [
    { "date": "2025-03-15", "tls_success_ratio": 1.0 }
  ],
  "delivery_errors_data": [
    { "date": "2025-03-15", "errors": [] }
  ]
}

Response Fields

Field	Description
`spam_rate_data`	Daily spam rate as reported by Gmail users
`ip_reputation_data`	IP reputation distribution (high/medium/low/bad)
`domain_reputation_data`	Overall domain reputation: `HIGH`, `MEDIUM`, `LOW`, or `BAD`
`feedback_loop_data`	Spam complaints and feedback loop signals
`authentication_data`	SPF, DKIM, and DMARC pass rates
`encryption_data`	TLS encryption success rate
`delivery_errors_data`	Delivery error details

Error Responses

404 — Account or domain not found:

{
  "error": "Invalid ID or account not found."
}

{
  "error": "No data available for the selected domain"
}

422 — Validation errors:

{
  "error": "Email parameter is required"
}

{
  "error": "Both start_date and end_date must be present"
}

{
  "error": "Invalid date format. Use YYYY-MM-DD."
}

Code Examples

# List connected accounts
curl -X GET "https://app.inboxissue.com/api/v1/postmaster_accounts/connected" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# Get cumulative data for a connected account
curl -X GET "https://app.inboxissue.com/api/v1/postmaster_accounts?email=admin@yourcompany.com" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# Get domain-specific data with date range
curl -X GET "https://app.inboxissue.com/api/v1/postmaster_accounts/42?email=admin@yourcompany.com&item=yourcompany.com&start_date=2025-03-01&end_date=2025-03-15" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests
 
API_TOKEN = "your_api_token"
BASE_URL = "https://app.inboxissue.com/api/v1"
headers = {"Authorization": f"Bearer {API_TOKEN}"}
 
# List connected accounts
accounts = requests.get(f"{BASE_URL}/postmaster_accounts/connected", headers=headers).json()
 
for account in accounts["connected_accounts"]:
    print(f"Account: {account['email']} (ID: {account['id']})")
 
    # Get domain data
    data = requests.get(
        f"{BASE_URL}/postmaster_accounts/{account['id']}",
        headers=headers,
        params={
            "email": account["email"],
            "item": "yourcompany.com",
            "start_date": "2025-03-01",
            "end_date": "2025-03-15"
        }
    ).json()
 
    for entry in data.get("domain_reputation_data", []):
        print(f"  {entry['date']}: {entry['reputation']}")

Deliverability Insights

Understanding reputation metrics

Authentication

API tokens and auth

Error Handling

Error codes and best practices

Postmaster Accounts API

Deliverability Insights

Authentication

Error Handling

On this page