Check a list freeCheck free
Home/Developer Documentation
EMAIL VERIFICATION, EXPLAINED

Build with a clear contract. Developer documentation & API reference.

Integration principles, deterministic HTTP semantics, RFC 5321/5322 compliance, and machine-readable result contracts for modern engineering teams. Build real-time signup validation, batch pipelines, signed webhooks, and AI agent workflows with zero false assumptions.

Deterministic API contracts.

Sub-180ms verification latency, fail-open resilience, signed HMAC webhooks, and native MCP agent support.

MAILCHECKUP / DOCS↘
Sub-180ms Latency SLA Fail-Open Reliability Pattern HMAC-SHA256 Signed Webhooks Native MCP Agent Protocol
INTERACTIVE API PLAYGROUND

Explore Endpoints & Request Contracts

Test REST endpoints, toggle between client languages (cURL, Node.js, Python, Go), and simulate realistic JSON responses.

RFC 5321 / 5322 Standards Zero-Leak Security
REQUEST CONTRACT

GET /v1/verify

Synchronous, sub-180ms verification for real-time form inputs and SaaS signups.

request.sh 
curl -X GET "https://api.mailcheckup.net/v1/verify?email=alex.morgan%40acme-corp.com" \
  -H "Authorization: Bearer mck_live_948f20a9bc41" \
  -H "Accept: application/json"
RESPONSE SIMULATOR

Response Payload & Ledger Impact

200 OK ⏱️ 138ms 1 credit billed
Mailbox positively confirmed by destination mail server. Safe for high-priority sequencing and critical user notifications.
response.json 
{
  "status": "success",
  "data": {
    "email": "alex.morgan@acme-corp.com",
    "outcome": "deliverable",
    "reason": "DELIVERABLE_250_OK",
    "is_deliverable": true,
    "is_disposable": false,
    "is_catchall": false,
    "is_role": false,
    "is_free_provider": false,
    "mx_host": "aspmx.l.google.com",
    "latency_ms": 138,
    "credits_charged": 1
  }
}
CONTRACT DIRECTORY & GUIDES

Developer Field Guides & Protocol Specifications

Browse detailed integration contracts across authentication, batch jobs, webhook security, and AI agent connectors.

GETTING STARTED Core Contract

Before your first API request

Authentication headers, base URL contracts, sandbox testing conventions, and separating sample mocks from live production verification.

Read contract ↗
AUTHENTICATION & SAFETY Security Standard

Protect your API credentials

Bearer token header standards, server-side credential isolation, environment variable injection, and automated secret rotation procedures.

Read contract ↗
ENDPOINTS & WORKFLOWS Real-Time SLA

Handle one address deliberately

Sub-180ms single email checks for SaaS onboarding, signup forms, and synchronous validation with client-side timeout budgets.

Read contract ↗
ENDPOINTS & WORKFLOWS Batch Engine

Treat bulk verification as a job

Asynchronous job ingestion, chunked progress polling, resumable uploads, and graceful failure recovery for lists up to 1,000,000 rows.

Read contract ↗
CONTRACTS & REASON CODES Data Integrity

Keep reason codes intact

Preserve granular machine-readable reason enums in client databases without collapsing inconclusive or unknown outcomes into hard invalid.

Read contract ↗
CONTRACTS & REASON CODES Architecture Pattern

Separate errors from verdicts

HTTP transport errors (400, 401, 402, 429, 500) vs. verification verdicts (valid, invalid, risky, unknown). Test failure paths deterministically.

Read contract ↗
CAPACITY & THROUGHPUT Concurrency Envelope

Respect the actual limits

Rate limit headers (X-RateLimit-Remaining, Retry-After), per-minute request envelopes, and jittered exponential backoff algorithms.

Read contract ↗
CONTRACTS & REASON CODES Reliability Pattern

Prevent duplicate work

Idempotency-Key request headers, 24-hour cache scope, replay semantics, and preventing duplicate list credit reservations upon browser refresh.

Read contract ↗
WEBHOOKS & MCP Async Notification

Webhooks call your URL

Outbound event notifications for job lifecycles. Event schemas, retry schedules, and URL configuration guidelines.

Read contract ↗
CONTRACTS & REASON CODES Ledger Accounting

Know what was reserved and charged

Reconcile account balance ledgers, reservation holds, billable completions, and automatic hold release for inconclusive unknown outcomes.

Read contract ↗
WEBHOOKS & MCP AI Agent Protocol

Model Context Protocol (MCP) server

Connect Cursor, Claude Desktop, and autonomous agents to MailCheckup verification tools via JSON-RPC 2.0 streamable HTTP.

Read contract ↗
WEBHOOKS & MCP Cryptographic Safety

Webhook signatures & event reference

Verify X-MailCheckup-Signature using HMAC-SHA256 with timestamp tolerance against replay attacks. Includes exact code examples.

Read contract ↗
ON THIS PAGE
  1. Core verification engine architecture & latency
  2. Reason codes & machine-readable ledger contracts
  3. Idempotency keys, rate limits, & concurrency
  4. Resilient client integration checklist
  5. Frequently asked developer questions

1. Core verification engine architecture & latency

The MailCheckup verification engine runs a pipeline of deterministic checks against target email addresses. Checks execute in strict progressive sequence: if an early stage decisively proves an address invalid (such as syntax errors or missing DNS MX records), subsequent network checks are bypassed to conserve resources and minimize round-trip latency:

Verification StageUnderlying Network CheckTarget LatencyRFC Standard ComplianceActionable Result Code
1. Syntax & FramingRegEx & Punycode normalization1ms–3msRFC 5321, RFC 5322, RFC 6530INVALID_SYNTAX_FORMAT
2. DNS & MX RecordsAuthoritative nameserver resolution15ms–35msRFC 1035, RFC 7505 (Null MX)INVALID_MX_MISSING
3. Throwaway Blocklist97,000+ domain hash lookup5ms–12msUpdated every 6 hoursDISPOSABLE_DOMAIN_MATCH
4. SMTP Mailbox DialDirect TCP port 25 interrogation120ms–180msRFC 5321 EHLO/RCPT TO handshakeDELIVERABLE_250_OK / 550_NOT_FOUND
5. Catch-All InterrogationDynamic probe mailbox verification140ms–210msMulti-probe heuristicsRISKY_CATCHALL_DOMAIN
6. Server Greylisting / WaitUpstream delay detectionImmediate deferralRFC 5321 451/421 GreylistingUNKNOWN_UPSTREAM_GREYLIST ($0 Free)

For synchronous user onboarding (such as registration forms and checkout validation), our API guarantees sub-180ms p95 latency on standard non-greylisted domains. When upstream servers defer connection, our fail-open architecture empowers engineering teams to maintain seamless customer onboarding without sacrificing sender safety.

2. Reason codes & machine-readable ledger contracts

Client applications must never flatten nuanced verification verdicts into a simple binary valid/invalid boolean. A deferred check due to remote greylisting is categorically distinct from a confirmed 550 Mailbox Not Found rejection. MailCheckup returns consistent, stable enum values across all API responses:

Reason Code EnumOutcome ClassHTTP StatusCredit ChargeLedger Hold ReleaseOperational Meaning
DELIVERABLE_250_OKdeliverable200 OK1 creditSettled on finishMailbox verified. Recipient positively accepted.
INVALID_550_MAILBOX_NOT_FOUNDundeliverable200 OK1 creditSettled on finishMailbox permanently rejected (550 user unknown).
INVALID_SYNTAX_FORMATundeliverable200 OK1 creditSettled on finishMalformed local part or illegal domain characters.
INVALID_MX_MISSINGundeliverable200 OK1 creditSettled on finishDomain lacks MX records or points to Null MX (RFC 7505).
DISPOSABLE_DOMAIN_MATCHrisky200 OK1 creditSettled on finishTemporary burner inbox. Protect SaaS trial abuse.
RISKY_CATCHALL_DOMAINrisky200 OK1 creditSettled on finishDomain accepts all emails. Individual mailbox unconfirmed.
RISKY_ROLE_ACCOUNTrisky200 OK1 creditSettled on finishShared corporate alias (sales@, info@, billing@).
RISKY_MAILBOX_FULLrisky200 OK1 creditSettled on finishValid mailbox confirmed, but target storage quota full.
UNKNOWN_UPSTREAM_GREYLIST_451unknown200 OK0 credits ($0)Immediate releaseAnti-spam delay; retry in 15m. 100% Free guarantee.
UNKNOWN_CONNECTION_TIMEOUTunknown200 OK0 credits ($0)Immediate releaseRemote server timed out on port 25. 100% Free guarantee.
UNKNOWN_FIREWALL_BLOCKEDunknown200 OK0 credits ($0)Immediate releaseRemote policy blocked check. 100% Free guarantee.
DUPLICATE_ROW_IGNOREDduplicate200 OK0 credits ($0)No credit holdAddress verified once, billed once in list.

Under our $0 Free Unknown Guarantee, any address resulting in an inconclusive check costs exactly 0 credits. Reservation holds placed during bulk job initialization are released back to your available ledger balance immediately upon job settlement.

3. Idempotency keys, rate limits, & concurrency

Financial ledger systems and verification APIs require strict idempotency semantics to prevent double-charging or duplicate work during network retries. When creating bulk verification jobs, pass an Idempotency-Key header:

  • 24-Hour Cache Window: If an identical request with the same idempotency key is received within 24 hours, the server returns the originally generated job payload without deducting additional credits.
  • Graceful Degradation: If a network timeout occurs while waiting for job creation, simply replay the request with the identical key.
  • Rate Limit Envelopes: Requests are metered per minute according to your active workspace subscription:
API TierMonthly Credit VolumeRate Limit EnvelopeConcurrent Batch ListsMax Rows / FileFail-Open Budget Recommendation
Free Trial100 credits30 requests/minute2 simultaneous lists5,000 rows350ms AbortSignal
Starter ($19/mo)5,000 credits60 requests/minute10 simultaneous lists50,000 rows300ms AbortSignal
Growth ($39/mo)25,000 credits120 requests/minute25 simultaneous lists250,000 rows250ms AbortSignal
Business ($199/mo)100,000 credits240 requests/minute50 simultaneous lists500,000 rows200ms AbortSignal
Scale ($449/mo)500,000 credits300 requests/minute100 simultaneous lists1,000,000 rows180ms AbortSignal

4. Resilient client integration checklist

Building mission-critical software requires anticipating external system failure. The matrix below outlines battle-tested engineering patterns for integrating email verification across synchronous and asynchronous workflows:

Integration ContextFailure ScenarioRecommended PatternArchitectural Safeguard
SaaS Registration FormMailCheckup API latency > 300msFail-open registrationDo not block customer signup; enqueue background check.
Bulk Outreach JobBrowser refresh during uploadPass Idempotency-Key headerPrevents duplicate list reservation holds for 24 hours.
Inbound Webhook ListenerAdversary spoofing webhook eventVerify HMAC-SHA256 signatureTiming-safe signature check against raw request body.
CRM Sync QueueUpstream server returns 451 greylistSchedule delayed retry (15m)Address was $0 Free; retry costs 0 additional dollars.
API Client429 Rate Limit ExceededExponential backoff with jitterPause execution for duration indicated in Retry-After header.

5. Frequently asked developer questions

How should our backend handle timeouts and greylisted servers without blocking users?

When validating emails synchronously during SaaS onboarding or checkout, configure a strict client-side timeout budget (e.g. 250ms–350ms) using an AbortSignal or context deadline. If MailCheckup returns an inconclusive timeout or greylisted 451 response, implement a fail-open pattern: allow user registration to proceed smoothly and enqueue a background asynchronous re-check for 15 minutes later.

Are unknown, timed-out, or deferred checks charged to our credit ledger?

No. MailCheckup operates under an unconditional $0 Free Unknown Policy. When remote mail servers defer interrogations, throttle requests, or time out on TCP port 25, the check is inconclusive. You are billed exactly 0 credits ($0.00), and all pre-authorized reservation holds on your workspace ledger are instantly released.

How does MailCheckup protect webhook endpoints against replay attacks?

Outbound webhook notifications include an X-MailCheckup-Signature header containing a timestamp and HMAC-SHA256 digest (format: t=1728691200,v1=hex). By computing HMAC-SHA256(secret, `${t}.${raw_body}`) and enforcing a strict 300-second timestamp tolerance window, your receiver prevents replay attacks and unauthorized spoofing.

What is the recommended idempotency key format, scope, and time-to-live?

Pass an Idempotency-Key header on all mutating POST requests (such as creating bulk jobs). Keys should be unique UUIDv4 strings or deterministic entity hashes (e.g., job_list_{hash}). MailCheckup caches idempotency responses for 24 hours. Replaying a request with the same key returns the existing job ID without reserving duplicate credits.

How do we test MailCheckup API integrations in staging environments without expending credits?

MailCheckup provides deterministic test addresses (such as test.deliverable@example.com, test.invalid@example.com, test.disposable@mailinator.com, and test.unknown@example.org). In sandbox mode or when using test keys, requests evaluate syntax and response formats with zero credit consumption.

Can our autonomous AI agents trigger email verification directly via MCP?

Yes. MailCheckup provides a native Model Context Protocol (MCP) server accessible at https://cp.mailcheckup.net/mcp via JSON-RPC 2.0 streamable HTTP. You can configure Cursor, Claude Desktop, or custom LLM orchestrators with your workspace Bearer token to inspect lead lists and scrub invalid contacts autonomously.

What rate limit headers are returned on REST API requests?

Every API response returns standard RFC rate limit headers: X-RateLimit-Limit (total allowed per window), X-RateLimit-Remaining (tokens remaining in current interval), and X-RateLimit-Reset (UTC epoch when quota resets). When throttled with HTTP 429, a Retry-After header indicates the exact seconds to pause.

How should engineering teams handle catch-all corporate domains in SaaS onboarding?

A catch-all domain accepts mail for any address unconditionally, meaning individual mailbox existence cannot be confirmed by SMTP alone. In SaaS onboarding, allow catch-all addresses to register if syntax and DNS MX records pass, but flag them internally for email confirmation link verification before granting access to sensitive platform features.

KEEP EXPLORING

A clearer next step.

Understand your results ↗Explore a sample check ↗Read the guides ↗