Mail Checker API — Sähköpostin validointi & toimitettavuus | YEB

#What Mailchecker solves

The endpoint helps you prevent bounces, typos, and low-quality signups. Use it at signup, checkout, or list imports to assess trust and risk, and optionally suggest corrections.

#Endpoint & when to use it

#POST /v1/mailchecker — Validate Email

• Best for: Inline form validation, CRM/ESP imports, fraud screening.
• How it works: You send an email string; we return a quality score, trust/risk labels, provider hints, and recommendations.
• Typical use: Client calls your backend; backend calls this endpoint and decides allow/confirm/block.

#Quick start

curl -X POST "https://api.yeb.to/v1/mailchecker" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "email": "[email protected]" }'

// JS Fetch example
fetch('https://api.yeb.to/v1/mailchecker', {
  method: 'POST',
  headers: {
    'X-API-Key': '<YOUR_API_KEY>',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({ email: '[email protected]' })
})
.then(r => r.json())
.then(console.log)
.catch(console.error);

#Parameters that actually matter

#Reading & acting on responses

{
  "email": "[email protected]",
  "trusted": "high",       // high | medium | low | unknown
  "score": 7,              // 0..10 (higher is better)
  "risk": "low",           // low | medium | high
  "knownProvider": true,   // e.g., Gmail, Outlook, iCloud, Yahoo, corporate domains, etc.
  "recommend": []          // suggestions (typo fixes or safer alternatives)
}

• trusted — overall confidence bucket. Use this for quick allow/step-up decisions.
• score — numeric quality (0–10). Great for thresholds (e.g., ≥6 allow, 3–5 require confirm, <3 block).
• risk — conservative view of potential bounce/misuse.
• knownProvider — true for common mailbox providers; false could indicate typos or private MX.
• recommend[] — suggested corrections (e.g., [email protected] if user typed gmal.com).

#Common scenarios

// Typo correction
{
  "email": "[email protected]",
  "trusted": "medium",
  "score": 5,
  "risk": "medium",
  "knownProvider": false,
  "recommend": ["[email protected]"]
}

// Disposable or risky domain
{
  "email": "[email protected]",
  "trusted": "low",
  "score": 2,
  "risk": "high",
  "knownProvider": false,
  "recommend": []
}

#Recommended actions

• Allow immediately: trusted = high and risk = low, or score ≥ 7.
• Step-up / confirm: score 3–6 → require email confirmation or show “Is this correct?” with recommend[].
• Block or require alternate contact: score < 3 or risk = high → don’t send transactional mail to it.
• Never silently “fix”: Offer suggested corrections; let the user choose.

#Practical recipes

• Inline signup: On blur, validate; if recommend[] not empty, present a one-click replace.
• Checkout fraud hardening: For new accounts with risk = high, add OTP or card 3DS challenge.
• List import: Batch through your backend; quarantine score < 3 rows and auto-mail confirm for 3–5.

#Troubleshooting & field notes

1. 422 “Missing email”: Send a non-empty email string.
2. 401 Unauthorized: Check your X-API-Key header and account credits.
3. Edge cases: Role accounts (e.g., info@) and private MX can be valid but lower trust; use the score threshold instead of hard-blocking.
4. Rate limits: Debounce form inputs; validate on blur/submit, not every keystroke.

#API Changelog