Email validations

What a validation checks#

A validation is a set of lookups, not a delivery attempt. No mail is sent and the recipient's mail server is never contacted, so a deliverable result means the address is well-formed and its domain publishes MX records — not that this particular mailbox exists. A typo in the local part (jhon@gmail.com) comes back deliverable.

checks.syntaxboolean

The address is well-formed. The request body is already validated as an email address before any check runs (a malformed address is a 400), so through the API this is always true.

checks.mxboolean

The domain has at least one MX record, looked up through public resolvers (8.8.8.8, 1.1.1.1). A domain with only an A record counts as no MX, and so does a lookup that times out or fails.

checks.disposableboolean

The domain is on PostStack's list of about 5,000 disposable/temporary inbox providers (e.g. mailinator.com). Exact domain match — subdomains of a listed domain are not flagged.

checks.roleboolean

The whole local part is a role name such as info, admin, support, billing, noreply or postmaster. Exact match: info.sales@ is not a role address.

checks.freeboolean

The domain is a free mailbox provider (Gmail, Outlook, Yahoo and similar). Informational only — it never changes result or risk.

Results are cached per address for one hour, so validating the same address again within the hour returns the earlier answer without repeating the DNS lookup — including an undeliverable caused by a DNS timeout.

How the verdict is decided#

The first matching row wins:

Endpoints#

Base URL https://api.poststack.dev. Authenticate with Authorization: Bearer sk_live_…; both full-access and sending-access API keys can validate. Rate limits apply per credential; over the limit you get 429 with a Retry-After header in seconds.

const validation = await poststack.emailValidations.validate(
  'alice@example.com',
);

if (validation.result === 'undeliverable') {
  // Ask the user to check the address before you create the account.
}

curl -X POST https://api.poststack.dev/email-validations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "alice@example.com" }'

{
  "email": "alice@example.com"
}

{
  "email": "alice@example.com",
  "result": "deliverable",
  "checks": {
    "syntax": true,
    "mx": true,
    "disposable": false,
    "role": false,
    "free": false
  },
  "risk": "low"
}

const { results } = await poststack.emailValidations.validateBatch([
  'alice@example.com',
  'bob@mailinator.com',
  'info@example.org',
]);

const keep = results.filter((r) => r.result === 'deliverable');

curl -X POST https://api.poststack.dev/email-validations/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "alice@example.com",
      "bob@mailinator.com",
      "info@example.org"
    ]
  }'

{
  "emails": [
    "alice@example.com",
    "bob@mailinator.com",
    "info@example.org"
  ]
}

{
  "results": [
    {
      "email": "alice@example.com",
      "result": "deliverable",
      "checks": { "syntax": true, "mx": true, "disposable": false, "role": false, "free": false },
      "risk": "low"
    },
    {
      "email": "bob@mailinator.com",
      "result": "risky",
      "checks": { "syntax": true, "mx": true, "disposable": true, "role": false, "free": false },
      "risk": "high"
    },
    {
      "email": "info@example.org",
      "result": "risky",
      "checks": { "syntax": true, "mx": true, "disposable": false, "role": true, "free": false },
      "risk": "medium"
    }
  ]
}

From other tools#

The same two calls in the Python SDK and the MCP server. You can also validate by hand on the Email validation page in the dashboard.

from poststack import PostStack

client = PostStack(api_key="sk_live_...")

one = client.email_validations.validate("alice@example.com")
many = client.email_validations.validate_batch(["alice@example.com", "bob@mailinator.com"])

validate_email        { "email": "alice@example.com" }
validate_email_batch  { "emails": ["alice@example.com", "bob@mailinator.com"] }

Troubleshooting#

Next steps