Skip to main content

Developer reference · v1

Email Validation API Reference

Overview

Product-true HTTP contract for Lucenri email verification. This page documents routes and fields implemented in production code. Results are decision-support signals — not inbox-delivery guarantees. Limits are deployment-published and may change; always read GET /api/config/public.

OpenAPI JSON Commercial overview Pricing

Not documented here as normal developer API: guest trial routes, /warmup, /accuracy-smoke, admin surfaces, or controlled mail-lab evidence flows.

Authentication

External integrations should authenticate with an API key header:

Request header

x-api-key: lcr_your_api_key
  • Keys use the lcr_ prefix.
  • API keys are for server-side integrations only. Never expose them in browser bundles or public clients.
  • API key use requires a verified account email. Unverified accounts receive HTTP 403.

Lucenri’s product web app may also authenticate with a session cookie or Authorization: Bearer <jwt>. JWT is product-app authentication — not the recommended primary path for external developers.

Base URL

Production base URL:

https://lucenri.com

Verification routes are mounted under /api/verify. Public config is under /api/config/public.

Verify one email

POST /api/verify/single · authenticated · synchronous · consumes 1 credit when accepted

JSON body

{
  "email": "[email protected]"
}

The server trims and lowercases the address. Missing or invalid input returns HTTP 400.

Successful response includes success, result, and current balance.

Verify a synchronous list

POST /api/verify/bulk · authenticated · synchronous JSON

JSON body

{
  "emails": [
    "[email protected]",
    "[email protected]"
  ]
}
  • This API accepts a JSON array. CSV/file upload is a Lucenri frontend workflow, not this request format.
  • Entries are trimmed, lowercased, filtered (must contain @, max length 254), and deduplicated.
  • If no usable email remains, the request fails with HTTP 400.
  • Lists at or above the published async threshold are rejected with asyncRequired: true. Use jobs instead.

Success returns results, balance, mode: "sync", optional batchId, and retention fields when available.

Create asynchronous verification job

POST /api/verify/jobs · authenticated · returns HTTP 202

Same JSON emails array contract as bulk. Use this path for lists at or above the published async threshold (and for any async workflow up to the published max).

Example 202 response fields

{
  "success": true,
  "mode": "async",
  "jobId": "…",
  "status": "queued",
  "total": 1200,
  "balance": 8800,
  "message": "Verification queued. Poll GET /api/verify/jobs/:id for progress."
}

Poll async job

GET /api/verify/jobs/:id · authenticated

Job status literals:

  • queued
  • processing
  • completed
  • failed

Poll responses include progress fields (processed, progress). Completed jobs may include batchId. For large result sets, prefer batch result endpoints rather than relying solely on inline poll payloads.

Batch history

GET /api/verify/batches · authenticated — recent scans for the authenticated account.

Batch detail / results

  • GET /api/verify/batches/:id — batch detail
  • GET /api/verify/batches/:id/results — paginated results

Missing or expired scans return HTTP 404.

CSV export

GET /api/verify/batches/:id/export.csv · authenticated — CSV export stream of batch results.

Mark download complete / purge

POST /api/verify/batches/:id/downloaded · authenticated — mark download complete; may purge retained payload.

Dynamic limits

GET /api/config/public (no auth) publishes deployment values including:

  • asyncVerifyThreshold
  • maxBulkEmails

Current product defaults are 1000 for the async threshold and 10000 for max bulk emails, but both are environment-configurable. Clients must read the published values and must not treat defaults as permanent API guarantees.

  • Below async threshold: synchronous /bulk is available.
  • At or above async threshold: use POST /api/verify/jobs.

There is no documented 500-email per-job API cap. Chunk/page sizes used internally are not a public upload ceiling.

Result schema

Public result object fields:

  • email — normalized address
  • valid — boolean decision-support flag
  • status — taxonomy literal
  • severity — success | warning | error | info
  • code — machine-oriented result code string (for example ok-valid, err-syntax)
  • confidence — integer 0–100 relative decision-support score; not a delivery guarantee
  • checks — array of { step, result, code } where result is pass | fail | skip

Optional when present: input_email, alias_normalized, free_email, domain_age_days.

disposable may appear as a deprecated boolean compatibility mirror when status is disposable. Prefer status.

There is no public reason or score field.

Status values

Stable public taxonomy:

  • valid
  • invalid
  • disposable
  • role
  • typo
  • catch_all
  • risky
  • unknown

Map these categories to your application policy. unknown and risky indicate uncertainty — treat as non-final for send decisions.

Verification checks

Always available in the local product path:

  • Syntax validation
  • Normalization (including common mailbox alias normalization)
  • Disposable detection
  • Typo-domain detection
  • Role-address detection
  • Public DNS / MX / null-MX related domain checks

Conditional:

  • SMTP recipient checks may run when enabled for the deployment.
  • Major mailbox providers may be skipped; results may remain unknown.
  • Catch-all probing may be attempted when SMTP probing runs. It is not guaranteed for every domain.

Lucenri does not promise inbox placement, universal SMTP probing, universal catch-all detection, or public ninety-nine-plus percent accuracy claims.

Credits

  • Verification consumes credits based on unique emails after server-side deduplication.
  • Credit availability is checked before processing.
  • Credits are reserved/deducted before verification execution.
  • Eligible synchronous failures refund deducted credits.
  • Failed or recovered asynchronous jobs refund reserved credits.
  • Insufficient credits return HTTP 402.

Commercial plan prices and credit packs are published on /pricing. Do not hard-code prices from older setup notes.

Errors

Common error envelope:

{
  "success": false,
  "error": "…"
}

Relevant HTTP statuses include 400, 401, 402, 403, 404, 429, 500, and 503.

HTTP status plus documented response fields are the stable integration signals. Free-text error strings are human-readable and should not be treated as a permanent machine enum.

For HTTP 429, inspect Retry-After and rate-limit headers when present, and honor retryAfterSec in the JSON body when returned.

Rate limits

The API is rate limited. Exact numeric ceilings are configuration-dependent and may change by deployment.

  • Clients must handle HTTP 429.
  • When returned, inspect X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After.

Do not hard-code a permanent requests-per-minute SLA from documentation examples.

Retention

Current deployment default retention for verification batch payloads is 72 hours, but retention is environment-configurable. Prefer returned retentionHours / expiry fields when present, and download or export results promptly.

POST /api/verify/batches/:id/downloaded may purge retained result data after download.

OpenAPI specification

Machine-readable contract: /features/email-validation-api/openapi.json (OpenAPI 3.0.3). Recommended public integration paths are JSON single/bulk and async jobs — not SSE.

Advanced: Lucenri web-product streaming transport

POST /api/verify/bulk/stream is an authenticated Server-Sent Events transport used primarily by the Lucenri web product for synchronous lists below the async threshold. Event payloads use data: {json} with type values such as start, progress, complete, and error.

For public integrations, prefer POST /api/verify/bulk (sync JSON) and POST /api/verify/jobs (async). SSE is not the primary OpenAPI v1 surface.

Optional health

GET /api/verify/ping — unauthenticated readiness ping returning success, service, and ready.

Accuracy / SMTP / catch-all limitations

  • Verification supports product decisions; it does not guarantee mailbox existence or inbox placement.
  • SMTP recipient checks are conditional and may be skipped for major providers.
  • Catch-all detection is conditional and not universal.
  • Confidence is relative decision support (0–100), not a delivery percentage claim.