Single call. Decisive verdict.

Overview

The API exposes one verification endpoint today. It accepts a single email address and returns a classification decided by the same validator the dashboard uses — no separate ruleset, no silent downgrade. All responses carry Cache-Control: no-store and a X-RateLimit-Remaining header.

Authentication

Every API call must carry a bearer token in the Authorizationheader. Tokens are issued from the dashboard and are shown once on creation — only the SHA-256 digest is stored server-side, so a lost key cannot be recovered, only revoked and replaced.

Authorization: Bearer pl_live_a1b2c3d4e5f6…

Creating a key

1. Sign in to your dashboard.
2. Open the API keys panel.
3. Name the key (e.g. production-api), hit Generate, and copy the plaintext token immediately. It will never be shown again.
4. Paste it into your server’s secret store. Never commit keys to source control or ship them in client-side bundles.

Key details

Rate limits

Each key carries its own token bucket. You can burst up to ten requests immediately, and the bucket refills at one request per second thereafter. Limits are enforced per key, not per account — high-volume services should use a dedicated key.

Clients should honour Retry-Afterwith a sleep or queue — retrying immediately will simply 429 again.

Errors

Every error response is JSON with a single error key describing what went wrong. No stack traces, no PII.

{ "error": "Missing bearer token" }

Validate an email

Verifies a single email address. The validator attempts up to three SMTP handshakes before returning — uncertain probes are resolved into a definitive invalid rather than exposed to the client.

Request body

Response body

Example

curl https://app.postelist.com/api/v1/validate \
  -H "Authorization: Bearer pl_live_a1b2c3d4e5f6…" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@postelist.com"}'

{
  "email": "ada@postelist.com",
  "classification": "deliverable"
}

Classifications

The API returns one of two values. There is no risky, no catch-all, no unknown— probes that cannot be resolved after retries are recorded as invalid rather than handed back as a maybe.

• deliverable

  The receiving mail server confirmed the mailbox exists and is accepting mail. Safe to send.

• invalid

  The mailbox does not exist, the domain does not accept mail, or the address could not be confirmed after three attempts. Do not send.