Quickstart

1. Get an API key

curl -X POST https://api.mercury.example.com/v1/keys \
  -H "Authorization: Bearer <session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{"label":"first-key","env":"live"}'

2. Verify an email

curl "https://api.mercury.example.com/v1/[email protected]" \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx"

{
  "email": "[email protected]",
  "verdict": "valid",
  "risk_score": 7,
  "checks": {
    "format":     { "ok": true },
    "mx":         { "ok": true, "hosts": ["alt1.gmail-smtp-in.l.google.com"] },
    "disposable": { "is_disposable": false, "source": "vendored+custom" },
    "role":       { "is_role": false, "role": null },
    "smtp":       { "ok": true, "code": 250, "latency_ms": 312 },
    "reputation": { "score": 12, "risk": "low", "signals": [] }
  },
  "cached": false,
  "cache_ttl_seconds": 3600,
  "verified_at": "2026-08-02T10:21:00Z"
}

3. Read the verdict

verdict	meaning
`valid`	SMTP server confirmed the mailbox exists (Pro+ only)
`invalid`	Hard fail — bad format, no MX, or recipient rejected
`risky`	Soft signal — disposable, role, catch-all, or reputation flag
`unknown`	Could not conclude — timeout, grey-list, or upstream unavailable