Skip to content
Mercury Mercury API

Quickstart

1. Get an API key

Sign up at the portal, then create a live key:

Terminal window
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

Terminal window
curl "https://api.mercury.example.com/v1/verify?email=user@example.com" \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx"
{
  "email": "user@example.com",
  "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

verdictmeaning
validSMTP server confirmed the mailbox exists (Pro+ only)
invalidHard fail — bad format, no MX, or recipient rejected
riskySoft signal — disposable, role, catch-all, or reputation flag
unknownCould not conclude — timeout, grey-list, or upstream unavailable