Email Verification API

Quick start

Generate an API key from your dashboard, then make your first request:

# 1. Get your API key from the dashboard
# 2. Make your first request:
curl -X POST https://stopbouncing.com/api/v1/verify \
  -H "Authorization: Bearer sb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# Expected response:
# { "email": "test@example.com", "status": "valid", "credits_remaining": 99 }

All requests require an Authorization header with your API key as a Bearer token. Never include your API key in client-side code.

Authorization: Bearer sb_your_api_key_here

Generate and manage keys at /dashboard/api-keys. Keys can be labelled per environment and revoked instantly.

Verify endpoint

Single endpoint, two methods. Both return the same response.

POST — JSON body

curl -X POST https://stopbouncing.com/api/v1/verify \
  -H "Authorization: Bearer sb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@acme.com"}'

GET — query parameter

Useful for quick tests. URL-encode the email address.

curl "https://stopbouncing.com/api/v1/verify?email=jane.doe%40acme.com" \
  -H "Authorization: Bearer sb_your_api_key_here"

Response format

All responses are JSON. A 200 status means the verification completed — check the status field for the result.

{
  "email": "jane.doe@acme.com",
  "status": "valid",
  "credits_remaining": 9842
}

{
  "email": "nope@invaliddomain.xyz",
  "status": "invalid",
  "credits_remaining": 9841
}

{
  "email": "user@catchall-domain.com",
  "status": "unknown",
  "credits_remaining": 9840
}

{
  "email": "temp123@mailinator.com",
  "status": "disposable",
  "credits_remaining": 9839
}

{
  "email": "info@acme.com",
  "status": "role",
  "credits_remaining": 9838
}

Status values

1 credit is charged for every request, regardless of the result. Why are unknown addresses not free?

HTTP status codes

Each API key is limited to 60 requests per minute. The limit resets on a rolling 60-second window per key.

On hitting the limit you receive a 429 with:

{
  "error": "Rate limit exceeded. Maximum 60 requests per minute per API key.",
  "retry_after": 60
}

All error responses share the same shape. Always check the HTTP status code first, then the error field for a human-readable message.

{
  "error": "Invalid or revoked API key."
}

{
  "error": "Insufficient credits. Please top up your account at stopbouncing.com/dashboard/billing.",
  "credits_remaining": 0
}

{
  "error": "Rate limit exceeded. Maximum 60 requests per minute per API key.",
  "retry_after": 60
}

Best practices