Proper Check
Developer Hub · REST API v1

Email address verification API

Verify mailing lists programmatically — fewer bounces, better deliverability

Connect signup forms, CRMs and landing pages to EmailVerifier. Check email addresses via REST API in real time or bulk jobs — with transparent 1 request = 1 credit billing.

  • Real-time verification
  • Bulk up to 50,000 emails
  • 1 request = 1 credit
Generate API keyCreate accountOpenAPI / Redoc

Sample request

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_…" \
  -d '{"email":"user@company.com"}'

API knowledge base

Pick a topic — from authentication and credits to bulk jobs, webhooks and error codes.

APIEmail verification API

POST /verify — single address, sub-second result, valid/invalid/risky status.

Read more
APIBulk email verification

Mass-verify CSV lists — job queue, progress polling and CSV export.

Read more
APICredits & billing

Balance, API usage, 1 credit = 1 verification, HTTP 402 handling.

Read more
APIAPI keys & auth

Bearer ev_live_, token panel, secure key storage best practices.

Read more
APIWebhooks & integrations

verification.completed, HMAC signature, CRM and marketing automation.

Read more
APIOpenAPI reference

Full YAML spec, Redoc UI and HTTP error catalogue.

Read more

What is an email verification API?

A REST interface to validate addresses before you send campaigns.

An email verification API checks whether an address exists, whether the domain accepts mail, and whether the inbox is disposable or catch-all. You reduce bounce rate, protect sender reputation and improve inbox placement.

The API is served over HTTPS at /api/v1. Authenticate with a Bearer key (ev_live_…) or a dashboard session. Each successful POST /verify costs one credit — no subscription and no hidden fees on GET requests.

When to use an email validator API

Common integration scenarios in B2B products and marketing stacks.

Signup forms

Validate email in real time on registration — reject invalid and disposable before list insert.

CRM & lead capture

Clean leads from landing pages and webhooks — only deliverable addresses enter your pipeline.

List hygiene before campaigns

Bulk API before newsletter sends — fewer bounces, higher open rates and lower ESP cost.

SaaS platforms

Embed email checks in your product — credit-based billing simplifies customer pricing.

API credit model

Simple pricing: one verification request = one credit.

  • POST /verify charges 1 credit per successful request (HTTP 200) with ev_live_ keys, even if the same address was verified before via API. Sandbox keys (ev_test_) return mock results without debiting credits.
  • GET operations — balance, history, bulk job status, CSV export — are free.
  • Insufficient balance returns HTTP 402 (insufficient_credits). Engine errors (503) do not charge a credit.

Authentication & API keys

Secure access via the Authorization header.

  1. Sign in to the dashboard and open API tokens (/account/api).
  2. Create a production key (ev_live_) or sandbox test key (ev_test_) in the panel — the full secret is shown only once.
  3. Send the key as Authorization: Bearer ev_live_… — never in URLs or client-side code.
Authorization: Bearer ev_live_YOUR_API_KEY
Content-Type: application/json

Quick start — email verification API

Two calls: balance check and first verification.

1. Check credit balance

curl https://propercheck.pl/api/v1/credits \
  -H "Authorization: Bearer ev_live_YOUR_KEY"

2. Verify a single email address

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@company.com"}'

Single verification (real-time)

POST /api/v1/verify accepts JSON with an email field. The response includes status, score 0–100, provider (Google, Microsoft, regional hosts) and enrichment (MX, catch-all).

POST /api/v1/verify

JSON response structure

Fields returned after a successful verification.

{
  "verificationId": "ver_abc123",
  "email": "john@company.com",
  "status": "valid",
  "score": 92,
  "provider": "google",
  "enrichment": { "mxRecords": ["aspmx.l.google.com"], "catchAll": false },
  "creditsRemaining": 149
}

Email verification statuses

Classification used in API, dashboard and CSV exports.

valid

valid — address exists and can receive mail; safe to send.

invalid

invalid — address does not exist or domain has no mail; remove from list.

risky

risky — low confidence (e.g. disposable, role account); use caution in campaigns.

catch_all

catch_all — server accepts all addresses on domain; higher bounce risk.

unknown

unknown — inconclusive SMTP response; consider re-verification later.

REST endpoint reference

Full API v1 path list with credit cost.

MethodPathCreditsDescription
POST/verify1Real-time single email verification
GET/verify/:id0Fetch result by verificationId
GET/verifications0Verification history and 30-day stats
GET/credits0Current account credit balance
POST/bulkNCreate bulk job (N credits)
GET/bulk/:id0Bulk job status and progress
GET/bulk/:id/export0Download results as CSV
GET/POST/PATCH/DELETE/api-keys0API token management (session)
GET/POST/DELETE/webhooks0Webhook configuration (session)
GET/usage0API and credit usage statistics

Bulk email verification API

Verify thousands of addresses in one job — ideal before large campaigns.

  1. POST /bulk with emails array or CSV text — credits reserved for N unique addresses.
  2. GET /bulk/:id — poll status (queued → processing → completed).
  3. GET /bulk/:id/export — download CSV with email, status, score, provider columns.
curl -X POST https://propercheck.pl/api/v1/bulk \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@b.co","c@d.co"]}'

Webhooks — verification.completed

Receive a POST to your URL when verification completes. Header X-EV-Signature contains HMAC-SHA256 of the body — verify before processing.

X-EV-Event: verification.completed
X-EV-Signature: <hmac-sha256 of body>

Rate limits

Default 60 requests per minute per API key. Exceeding returns HTTP 429 with rate_limit_exceeded. Limits are per key — use separate tokens per integration.

Optional header on POST /verify — safe retries without double credit debit for the same key (24h TTL).

X-Request-Id

Every API response includes X-Request-Id — include it when contacting support for integration debugging.

HTTP error codes

HTTPCodeDescription
401unauthorizedMissing session or API key in the request.
401invalid_api_keyInvalid, expired or revoked API key.
400invalid_requestInvalid JSON, missing email field or malformed address.
402insufficient_creditsInsufficient credits — top up at /account/credits.
429rate_limit_exceededRate limit exceeded — default 60 requests/min per API key.
503engine_unavailableVerification engine unavailable — no credit charged.

Integration examples

Same verification flow in popular languages.

curl -X POST https://propercheck.pl/api/v1/verify \
  -H "Authorization: Bearer ev_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"john@company.com"}'

FAQ — email verification API

Common questions from developers and marketers.

OpenAPI 3.1 & Redoc

Machine-readable spec for codegen, contract tests and CI pipelines.

Download openapi-v1.yamlInteractive Redoc reference

Start verifying emails via API

Free trial credits on signup. API key in your dashboard within a minute.

Create accountAPI tokens

Generate your key in the account panel.