Integrating real-time email verification into your application stack prevents malformed addresses, spam traps, and disposable domains from polluting your database before bad data ever enters your pipeline. Whether you are validating new signups in a web registration form, vetting leads in a CRM workflow, or cleaning batch dispatches via webhooks, integrating the MailVeri REST API takes only minutes.
Getting Started
Before initiating API calls, you need three core components ready in your development environment:
- MailVeri Account: An active MailVeri account with available verification credits (new accounts receive free credits on signup).
- Production API Key: Your secure secret key, accessible from the API Keys section of your MailVeri dashboard.
- HTTP Client: Standard HTTP client libraries in your application stack (such as
fetch,axios, Pythonhttpxorrequests, Gonet/http, or cURL) configured with standard connection timeouts.
You can review full endpoint schemas in our Developer Documentation or test individual queries interactively in the MailVeri Email Checker.
API Overview
The MailVeri API is a low-latency, stateless REST interface communicating over HTTPS with JSON payloads. The primary endpoint for real-time single email verification executes sub-second SMTP probes and DNS telemetry without sending test messages:
POST https://api.mailveri.com/v1/verify-mail/ (form-data: mail=test@example.com)For high-volume background imports or CSV processing, MailVeri provides dedicated asynchronous bulk endpoints (/v1/verify-mails/) that process up to 1,000,000 records asynchronously with status polling and webhook dispatches.
Authentication
All requests require Bearer token authentication passed in the standard HTTP Authorization request header:
Authorization: Bearer YOUR_API_KEYStore your secret key in server-side environment variables or secret vaults. Never expose this key in client-side browser bundles or public source code repositories.
Response Format
The endpoint returns a structured JSON payload containing the canonical verification status, deliverability indicators, and remaining credit balance:
{
"error": 0,
"message": "Verified test@example.com successfully",
"status": "VALID",
"mail": "test@example.com",
"balance": 999
}The status field provides a decisive verdict: VALID (mailbox verified and deliverable), INVALID (non-existent user, dead MX, or syntax defect), DISPOSABLE (temporary burner address), ROLE_ACCOUNT (generic alias such as support@ or billing@), CATCH_ALL (domain accepts all local parts without confirming recipient existence), or UNKNOWN (temporary remote server deferral).
Best Practices
To ensure maximum system reliability and a seamless user experience, implement these engineering best practices across your verification integration:
- Asynchronous Front-End Validation: Trigger verification when a user unfocuses (
blur) the email input or during form submission. Always enforce a short client-side timeout (e.g., 3 to 4 seconds) with a graceful fallback so a transient remote MTA timeout never blocks user onboarding. - In-Memory Caching & Deduplication: Cache verification results in Redis or Memcached with a 24- to 72-hour TTL. Prevent redundant external API lookups when users navigate back and forth across checkout or onboarding steps.
- Fail-Open Strategy for Critical Paths: On critical conversion funnels (such as account registration or enterprise signups), treat unexpected network timeouts or 5xx server errors as non-blocking (
fail-open). Flag the record internally for delayed background re-verification rather than rejecting the customer. - Respect Rate Limits & Thread Allocation: The API supports up to 10 concurrent requests per second by default. For bulk migrations or marketing list imports, use our batch endpoints with webhook notifications as detailed in our guide on standardizing webhook delivery.