Email Verification API & Developer Integration Hub
Integrate BounceLayer's sub-140ms email verification API and email validation service via standard REST endpoints, official language SDKs, or directly inside AI agents (Cursor, Claude, Windsurf) through our native Model Context Protocol (MCP) server.
Verify Emails Directly Inside Your AI Agent or IDE
Equip Claude Code, Cursor, Windsurf, or custom LangChain agents with real-time email verification. Run our official MCP server launcher with one command:
claude mcp add --transport http bouncelayer https://bouncelayer.com/mcp/ --header "X-API-Key: bl_live_..."1. Authentication & API Keys
All requests to the BounceLayer API require an API key passed in the X-API-Key header or as a Bearer token. Generate keys inside your API Keys Dashboard.
2. Real-Time Single Verification
Executes a live 7-layer verification in under 150ms. Checks syntax, authoritative DNS, MX hosts, disposable firewalls, and conducts a direct TCP port 25 SMTP handshake to confirm whether the recipient mailbox accepts mail.
Deducts 1 credit for deliverability verdicts (valid, invalid, catch_all, do_not_mail). Unknown results are 100% free (0 credits charged).
3. Asynchronous Bulk Verification
Process lists of up to 10,000 addresses in parallel. Specify an optional webhook_url to receive cryptographic HMAC-signed notifications when verification finishes.
| Endpoint | Method | Cost | Description |
|---|---|---|---|
| /api/v1/verify/bulk | POST | Reserves N | Queue batch job |
| /api/v1/verify/bulk/{id} | GET | FREE | Poll status & results |
| /api/v1/verify/bulk/{id} | DELETE | FREE | Cancel & release credits |
| /api/v1/verify/bulk/{id}/download | GET | FREE | Export CSV/JSON results |
4. Granular Status Reason Matrix
BounceLayer provides machine-readable diagnostic reasons for every single evaluation so automated pipelines can filter leads with pinpoint accuracy:
| status_reason | Primary Status | Credit Cost | Explanation |
|---|---|---|---|
| mailbox_confirmed | valid | 1 Credit | Remote mail server confirmed mailbox exists with 250 OK |
| mailbox_not_found | invalid | 1 Credit | Remote mail server returned 550 User Unknown |
| failed_syntax_check | invalid | 1 Credit | Malformed address failing RFC 5322 structure |
| no_dns_entries | invalid | 1 Credit | Target domain does not exist in public authoritative DNS |
| no_mx_records | invalid | 1 Credit | Domain has no valid Mail Exchanger (MX) records |
| disposable | do_not_mail | 1 Credit | Matches 100,000+ temporary burner domains |
| role_based | do_not_mail | 1 Credit | Generic departmental account (e.g. info@, support@) |
| accept_all | catch_all | 1 Credit | Domain accepts all addresses; specific mailbox cannot be isolated |
| antispam_system | unknown | 0 Credits (Free) | Remote MTA blocked probe or requires human challenge |
| failed_smtp_connection | unknown | 0 Credits (Free) | TCP port 25 connection timed out or dropped |
| greylisting | unknown | 0 Credits (Free) | Remote MTA deferred connection per greylisting policy |
5. HTTP Error Standards & Rate Limits
| Status | Code Meaning | Handling Strategy |
|---|---|---|
| 401 Unauthorized | Invalid or missing API key | Verify X-API-Key header |
| 402 Payment Required | Zero credits remaining | Top-up credits in dashboard |
| 413 Payload Too Large | Batch exceeded 10,000 limit | Chunk requests into 10K batches |
| 429 Rate Limited | Per-minute threshold met | Inspect Retry-After header and back off |
6. Webhooks & Real-Time Event Streaming
Receive instant HTTP POST notifications whenever asynchronous bulk list jobs finish or verification thresholds are met. Configure a persistent endpoint in the Webhooks Dashboard or supply a per-job webhook_url on submission.
| Event Name | Trigger Point | Included Payload Data |
|---|---|---|
| job.completed | Bulk list verification finishes | total_emails, valid_count, invalid_count, results_url |
| job.started | Taskiq worker begins processing | job_id, started_at, total_emails |
| job.failed | Worker encountered unrecoverable error | job_id, error_message |
| verification.completed | Single verification event (stream) | email, status, confidence_score, latency_ms |
| job.cancelled | Job manually stopped | job_id, credits_refunded |
Every webhook request delivers an X-BounceLayer-Signature header computed over the exact UTF-8 raw request payload using your secret key:
Your webhook destination must return an HTTP 2xx status within 5 seconds. If your endpoint returns 4xx/5xx or times out, BounceLayer automatically retries up to 5 times using exponential backoff:Attempt 1: immediate → Attempt 2: +1 min → Attempt 3: +2 min → Attempt 4: +4 min → Attempt 5: +8 min
curl -X POST https://bouncelayer.com/api/v1/verify/single \
-H "X-API-Key: bl_live_9a8b7c6d5e4f3a2b1c0d" \
-H "Content-Type: application/json" \
-d '{
"email": "alex@company.com"
}'{
"success": true,
"credits_used": 1,
"result": {
"email": "alex@company.com",
"status": "valid",
"is_valid": true,
"syntax_valid": true,
"domain": "company.com",
"domain_valid": true,
"has_mx": true,
"mx_records": [
{
"priority": 10,
"host": "aspmx.l.google.com"
}
],
"smtp_checked": true,
"smtp_response_code": 250,
"is_disposable": false,
"is_role_based": false,
"is_catch_all": false,
"is_free_provider": false,
"confidence_score": 98,
"status_reason": "mailbox_confirmed",
"provider": "google",
"verification_time_ms": 138,
"cached": false
}
}