API Documentation

Integrate MailProbe email validation into your applications.

Authentication

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/validate
Rate Limiting

Default rate limit is 100 requests per hour per API key. Rate limit headers are included in every response:

  • X-RateLimit-Limit — Maximum requests per hour
  • X-RateLimit-Remaining — Requests remaining
  • X-RateLimit-Reset — Time until limit resets (Unix timestamp)
Error Responses

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 key
400Invalid request body
429Rate limit exceeded
500Server error

Endpoints

POST/api/validate
Validate Email

Validate 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"}'
POST/api/bulk
Bulk Validate

Submit 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"]}'
GET/api/bulk/:jobId
Get Bulk Job Status

Check 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"
POST/api/keys
Create API Key

Generate 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"}'
Risk Scoring

MailProbe computes a composite risk score from 0-100 based on multiple validation signals:

0-25Safe

Email is verified and trustworthy

26-50Low Risk

Minor concerns, likely valid

51-75Medium Risk

Multiple risk factors present

76-100High Risk

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)