API documentation

One endpoint for email, phone, and IP verification.

Authentication

Create an API key in the dashboard, then send it as a bearer token in the Authorization header (or as x-api-key).

Endpoint

POST /api/public/v1/verify
GET  /api/public/v1/verify?kind=email&value=...

Request body

{
  "kind": "email" | "phone" | "ip",
  "value": "jane@acme.io",
  "country": "US"   // optional, phone only
}

Response

{
  "kind": "email",
  "value": "jane@acme.io",
  "status": "valid" | "invalid" | "risky" | "unknown",
  "score": 0-100,
  "reason": string | null,
  "checks": { ... },
  "latency_ms": 128,
  "credits_remaining": 9932
}

Examples

cURL

curl -X POST https://fishymails.com/api/public/v1/verify \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"kind":"email","value":"jane@acme.io"}'

Node / fetch

const res = await fetch("https://fishymails.com/api/public/v1/verify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.FISHYMAILS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ kind: "email", value: "jane@acme.io" }),
});
const data = await res.json();

Bulk verification

Verify up to 100 items in a single request. Each item costs 1 credit; if your balance runs out mid-request, the remaining items are skipped and reported in skipped.

POST /api/public/v1/verify/bulk

Request body

// Option A — mixed items
{
  "items": [
    { "kind": "email", "value": "jane@acme.io" },
    { "kind": "phone", "value": "+14155552671", "country": "US" },
    { "kind": "ip",    "value": "8.8.8.8" }
  ]
}

// Option B — shorthand arrays (can be combined)
{
  "emails": ["a@x.com", "b@y.com"],
  "phones": ["+3161234567"],
  "ips":    ["8.8.8.8"],
  "country": "NL"   // default country for shorthand phones
}

Response

{
  "count": 3,
  "skipped": 0,
  "credits_remaining": 9929,
  "latency_ms": 412,
  "results": [
    { "kind": "email", "value": "...", "status": "valid",   "score": 92, "checks": { ... }, "latency_ms": 128 },
    { "kind": "phone", "value": "...", "status": "valid",   "score": 88, "checks": { ... }, "latency_ms": 22  },
    { "kind": "ip",    "value": "...", "status": "risky",   "score": 41, "checks": { ... }, "latency_ms": 15  }
  ]
}

cURL

curl -X POST https://fishymails.com/api/public/v1/verify/bulk \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["jane@acme.io", "bob@mailinator.com"],
    "phones": ["+14155552671"],
    "ips": ["8.8.8.8"]
  }'

Pricing

1 credit is deducted per successful verification (regardless of result). Every account gets 100 free credits to start. Top up any time from the billing page.

Errors

401 — missing or revoked key
400 — invalid request body
402 — out of credits (response includes upgrade_url)