Bounso - Email Verification for Revenue Teams

Authentication

All API requests require authentication via an API key. To get your key:

Go to your Dashboard and navigate to API Keys.
Create a new key or copy your existing one.
Include it in every request via the Authorization header.

http

Authorization: Bearer sk_live_xxx

Important: All requests require authentication. Keep your API key secret and never expose it in client-side code.

Base URL

All API endpoints are relative to the following base URL:

url

https://api.bounso.com

Endpoints

POST/api/public/verify

Verify a single email address or a batch of emails.

Request Body

Single email:

json

{ "email": "user@example.com" }

Batch:

json

{ "emails": ["a@b.com", "c@d.com"] }

Responses

Single (cached result):

{
  "job_id": null,
  "status": "completed",
  "cached": true,
  "result": {
    "email": "user@example.com",
    "status": "valid",
    "confidence": 95,
    "mx_provider": "Google Workspace",
    "is_catch_all": false,
    "is_disposable": false,
    "is_role_account": false
  }
}

Single (queued):

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "cached": false
}

Batch:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "total": 100,
  "status": "queued"
}

GET/api/verify/status/[job_id]

Check the status and progress of a verification job.

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "total_emails": 100,
  "verified": 45,
  "valid": 38,
  "invalid": 5,
  "catch_all": 2,
  "unknown": 0,
  "progress_percent": 45
}

GET/api/results/[job_id]

Retrieve verification results for a completed job.

Query Parameters

Param	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 50)
`status`	string	Filter by status (valid, invalid, catch_all, unknown)

Response

{
  "results": [
    "..."
  ],
  "total": 100,
  "page": 1,
  "total_pages": 2
}

GET/api/credits

Check your current credit balance and plan details.

Response

{
  "credits": 5000,
  "plan": "pro",
  "total_verified": 12500
}

Rate Limits

Rate limits are applied per API key based on your plan.

Free

10 req/min

Starter

60 req/min

Pro

300 req/min

Scale

1,000 req/min

When rate limited, the API returns a 429 status code. Retry after the time specified in the Retry-After header.

Code Examples

Quick examples to get started with the Bounso API.

bash

curl -X POST https://api.bounso.com/api/public/verify \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Status Codes

The API uses standard HTTP status codes to indicate the outcome of requests.

Code	Description
200	Success
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
402	Insufficient Credits
404	Not Found — resource does not exist
429	Rate Limited — too many requests
500	Server Error — something went wrong on our end

Need help? Reach out to our team at support@bounso.com