VerifyBuddy API

A fast, RESTful email-verification API powered by our 14-layer engine. Verify a single address in real time, stream a batch, or run large bulk jobs — from any language or platform. JSON in, JSON out.

Base URL

https://api.verifybuddy.xyz/api/v1

JSON REST

Predictable resources, standard verbs, JSON responses.

API-key auth

One header: X-API-Key. Generate keys in the dashboard.

Rate + credit headers

Every response tells you what’s left.

Authentication

Authenticate every request with your secret API key in the X-API-Key header. Create and manage keys under Settings → API (keys are shown once — store them securely). Never expose a key in client-side code.

curl -X GET "https://api.verifybuddy.xyz/api/v1/email/credits" \
  -H "X-API-Key: YOUR_API_KEY"

Rate limits & credits

Limits are per API key and scale with your plan. Each response includes live usage headers. One credit is charged per fresh verification — repeats of the same address within 24h, cached results, and suppressed addresses are free.

Plan	Rate (req/min)
Free	10
Starter	60
Growth	120
Pro	300
Enterprise	600

Response headers:

X-Rate-Limit-Limit — your per-minute cap

X-Rate-Limit-Remaining — requests left this window

X-Credits-Remaining — credits left on the workspace

Over the limit returns 429; out of credits returns 402.

Verify a single email

POST/email/verify

Runs the full 14-layer engine on one address and returns a status + 0–100 score in real time. Charges 1 credit for a fresh verification.

Field	Type	Description
email	string	The email address to verify. Required.

curl -X POST "https://api.verifybuddy.xyz/api/v1/email/verify" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"someone@example.com"}'

Response

{
  "statusCode": 200,
  "data": {
    "email": "someone@example.com",
    "status": "VALID",
    "score": 98,
    "mxHost": "aspmx.l.google.com",
    "provider": "Google",
    "isFreeProvider": false,
    "creditsCharged": 1,
    "layers": {
      "syntax":     { "valid": true },
      "mx":         { "valid": true },
      "disposable": { "isDisposable": false },
      "roleBased":  { "isRoleBased": false },
      "smtp":       { "valid": true, "code": 250 },
      "catchAll":   { "isCatchAll": false }
    }
  },
  "message": "Verification complete"
}

Stream a batch (live, NDJSON)

POST/email/verify/stream

Verify up to 500 addresses in one request and receive results as NDJSON — one JSON object per line, streamed as each address completes. Great for progress UIs without polling. Charges per fresh verification.

Field	Type	Description
emails	string[]	Addresses to verify (max 500). Required.

curl -X POST "https://api.verifybuddy.xyz/api/v1/email/verify/stream" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@example.com","b@example.com"]}'

Response

{"email":"a@example.com","status":"VALID","score":98, ...}
{"email":"b@example.com","status":"INVALID","score":0, ...}
{"done":true,"total":2,"stopped":false}

Start a bulk job

POST/email/verify/bulk

Queue a large list for background processing. Returns a jobId to poll. Ideal for tens of thousands of addresses; results are retrievable via the job status endpoint or the dashboard (CSV export).

Field	Type	Description
emails	string[]	Addresses to verify. Required.
name	string	Optional label for the job.

curl -X POST "https://api.verifybuddy.xyz/api/v1/email/verify/bulk" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@example.com","b@example.com"],"name":"My list"}'

Response

{
  "statusCode": 201,
  "data": { "jobId": "clx…", "totalEmails": 2, "skipped": 0, "estimatedSeconds": 6 },
  "message": "Bulk job queued"
}

Bulk job status

GET/email/verify/bulk/{jobId}

Poll a bulk job's live progress: processed count, per-status breakdown, percent complete, and accurate processing time.

Field	Type	Description
jobId	string	The id returned by the bulk endpoint. Path param.

curl -X GET "https://api.verifybuddy.xyz/api/v1/email/verify/bulk/JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "statusCode": 200,
  "data": {
    "jobId": "clx…", "status": "PROCESSING",
    "totalEmails": 5000, "processed": 3200, "pct": 64,
    "valid": 2600, "invalid": 400, "risky": 120, "catchall": 60,
    "disposable": 10, "unknown": 10, "creditsUsed": 3200,
    "processingMs": 145000, "etaMs": 81000
  },
  "message": "Success"
}

Check credit balance

GET/email/credits

Returns the workspace's current credit balance and usage.

curl -X GET "https://api.verifybuddy.xyz/api/v1/email/credits" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "statusCode": 200,
  "data": { "balance": 48250, "used": 51750, "total": 100000 },
  "message": "Success"
}

Report a delivery outcome

POST/email/feedback

Tell the engine what actually happened after you emailed a verified address, so future checks get smarter. Free (no credit). A bounce makes future checks INVALID; a complaint flags it as a spam-trap risk.

Field	Type	Description
email	string	The address the outcome is for. Required.
event	"bounce" \| "complaint"	The delivery outcome. Required.

curl -X POST "https://api.verifybuddy.xyz/api/v1/email/feedback" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"someone@example.com","event":"bounce"}'

Response

{ "statusCode": 200, "data": null, "message": "Feedback recorded" }

Status reference

Every verification returns one status plus a 0–100 score (higher = safer to send).

Field	Type	Description
VALID	safe	Mailbox exists and accepts mail.
INVALID	unsafe	Mailbox does not exist / hard bounce.
RISKY	caution	Low-quality or risky (e.g. role-based, weak signals).
CATCHALL	caution	Domain accepts all addresses — can’t confirm the mailbox.
DISPOSABLE	unsafe	Temporary / throwaway address.
ROLE_BASED	caution	Role inbox (info@, support@, admin@…).
SPAM_TRAP	unsafe	Known spam-trap / complainer.
UNKNOWN	caution	Server didn’t give a definitive answer.

Errors

Errors use standard HTTP status codes and a consistent JSON shape.

Field	Type	Description
400	bad_request	Invalid input (e.g. malformed email or missing field).
401	unauthorized	Missing or invalid X-API-Key.
402	insufficient_credits	Out of credits — top up to continue.
404	not_found	Resource (e.g. bulk job) not found.
429	rate_limited	Too many requests — slow down / upgrade.

Response

{
  "statusCode": 402,
  "code": "INSUFFICIENT_CREDITS",
  "message": "You have 5 credits but need 10",
  "timestamp": "2026-08-05T10:00:00Z",
  "path": "/api/v1/email/verify"
}

Ready to integrate?

Generate an API key and paste any snippet above.

Get your API key