API Documentation
Integrate MailProbe email validation into your applications.
All API requests require an API key passed via the X-API-Key header. Generate keys from the API Keys page.
curl -H "X-API-Key: mp_your_api_key_here" https://mailprobe.talkytools.com/api/validateDefault rate limit is 100 requests per hour per API key. Rate limit headers are included in every response:
X-RateLimit-Limit— Maximum requests per hourX-RateLimit-Remaining— Requests remainingX-RateLimit-Reset— Time until limit resets (Unix timestamp)
All errors follow a consistent format:
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required. Provide a valid session or X-API-Key header."
}
}401Invalid or missing API key400Invalid request body429Rate limit exceeded500Server errorEndpoints
/api/validateValidate a single email address. Today the checks that run are syntax, DNS/MX, disposable list, role account, typo hints and risk score; mailbox (SMTP) and catch-all results are coming soon and may come back as unknown. The status field is one of safe, invalid, disabled, disposable, spamtrap, do_not_mail, inbox_full, catch_all, role_account, unknown, risky — only "safe" sets is_safe_to_send (spamtrap / do_not_mail come from the optional ZeroBounce fallback). did_you_mean suggests a fix for mistyped domains (gmai.com → gmail.com). For status catch_all, catch_all_confidence (0–100) and catch_all_label (likely_valid / uncertain / likely_invalid) estimate whether it is a real mailbox — from how name-like the address is, how it matches your other addresses at that domain, and Gravatar. It is a likelihood, never a confirmation: catch-all addresses are never safe to send. Mailbox fields (can_connect_smtp … is_disabled) are null when the mailbox check couldn't run; is_spamtrap is null unless the ZeroBounce fallback answered. overall_score = 100 − risk_score. Your own repeat checks are answered from your results of the last 7 days (30 minutes for unknown) — cached results are never shared between accounts.
curl -X POST https://mailprobe.talkytools.com/api/validate \
-H "Content-Type: application/json" \
-H "X-API-Key: mp_your_api_key_here" \
-d '{"email": "test@example.com"}'/api/bulkSubmit up to 500 emails for batch validation. Returns a job ID for tracking progress.
curl -X POST https://mailprobe.talkytools.com/api/bulk \
-H "Content-Type: application/json" \
-H "X-API-Key: mp_your_api_key_here" \
-d '{"emails": ["test@example.com", "user@gmail.com"]}'/api/bulk/:jobIdCheck the progress and results of a bulk validation job. Each result has the same fields as /api/validate. Addresses a mail server greylisted ("try again later") are re-checked automatically after 5 minutes, up to 2 times — the job stays "processing" meanwhile.
curl https://mailprobe.talkytools.com/api/bulk/abc123def456 \
-H "X-API-Key: mp_your_api_key_here"/api/keysGenerate a new API key for programmatic access. Requires session auth (cookie).
curl -X POST https://mailprobe.talkytools.com/api/keys \
-H "Content-Type: application/json" \
-H "Cookie: your-session-cookie" \
-d '{"name": "My App"}'MailProbe computes a composite risk score from 0-100 based on multiple validation signals:
Email is verified and trustworthy
Minor concerns, likely valid
Multiple risk factors present
Likely invalid or malicious
Scoring Factors (SMTP and catch-all factors apply only once mailbox checks go live, coming soon):
- Invalid syntax: +40
- No MX records: +30
- SMTP not deliverable: +20
- Disposable provider: +25
- Catch-all domain: +15
- Role account: +10
- Has Gravatar: -10 (positive signal)