ListBouncer API

The ListBouncer API lets you check single email addresses and clean whole lists from your own code, Zapier or other tools. It uses the same checks, the same results and the same credits as the dashboard.

Get a key

Create a key on the API keys page in your dashboard. You'll see it once, so copy it somewhere safe. Send it with every request:

Authorization: Bearer lb_live_…

Keep keys on your server. Anyone with your key can spend your credits, so don't put it in a web page or app that other people can see.

Credits

The API costs the same as the dashboard:

• Checking one address uses 1 credit, but only if we get a definite answer.
• Cleaning a list uses 1 credit per unique address. Duplicates and broken rows are free, and anything that comes back Unknown gets its credit back when the clean finishes.

New accounts get 100 free credits. Accounts that haven't bought credits yet can start up to 5 cleans a day.

Check one address

POST https://listbouncer.com/api/v1/verify

curl https://listbouncer.com/api/v1/verify \
  -H "Authorization: Bearer $LISTBOUNCER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@gmial.com"}'

{
  "email": "jane@gmial.com",
  "result": "will_bounce",
  "reason": "domain_typo",
  "explanation": "Looks like a typo for gmail.com. Check with the subscriber before using jane@gmail.com.",
  "suggested_fix": "jane@gmail.com",
  "charged": true,
  "credits_remaining": 4211
}

Most checks finish in a few seconds. Some mail servers are slow, so allow up to 30.

Clean a list

POST https://listbouncer.com/api/v1/lists

Send the addresses as JSON:

curl https://listbouncer.com/api/v1/lists \
  -H "Authorization: Bearer $LISTBOUNCER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "November newsletter", "emails": ["jane@example.com", "sam@example.org"]}'

Or upload a CSV file. We find the email column (and name columns) on our own:

curl https://listbouncer.com/api/v1/lists \
  -H "Authorization: Bearer $LISTBOUNCER_KEY" \
  -F "file=@subscribers.csv"

{
  "id": "6728e360-…",
  "status": "processing",
  "total": 2,
  "duplicates": 0,
  "malformed": 0,
  "credits_remaining": 4209
}

Up to 50,000 addresses and 4MB per request. Add "notify": true (or a notify=true form field) if you'd also like the "your list is clean" email.

Check progress

GET https://listbouncer.com/api/v1/lists/{id}

{
  "id": "6728e360-…",
  "name": "November newsletter",
  "status": "done",
  "total": 2,
  "processed": 2,
  "counts": { "safe": 1, "major_provider": 0, "risky": 0, "will_bounce": 1, "unknown": 0 },
  "created_at": "2026-11-12T09:00:00.000Z",
  "finished_at": "2026-11-12T09:01:12.000Z"
}

status is processing, done or failed. Most lists finish in minutes; very large ones can take longer. Checking every 30 seconds or so is plenty.

Get the results

GET https://listbouncer.com/api/v1/lists/{id}/results

Optional query parameters:

• group: only one group, e.g. group=safe for your clean list
• format: json (default) or csv
• limit: rows per page for JSON, up to 1,000
• cursor: the next_cursor from the previous page

{
  "data": [
    {
      "email": "jane@example.com",
      "result": "safe",
      "reason": null,
      "explanation": "The mailbox exists and accepts mail.",
      "suggested_fix": null,
      "first_name": "Jane",
      "last_name": null
    }
  ],
  "next_cursor": null
}

When next_cursor is null, you've got everything.

What the results mean

result	Meaning	What to do
safe	The mail server confirmed the mailbox exists.	Send to it. This is your clean list.
major_provider	Yahoo, Outlook, Hotmail or AOL. These providers don't let anyone confirm a mailbox.	Mail usually delivers. Send to these as their own segment.
risky	A catch-all domain, a shared inbox like info@, or a mixed answer.	Your call.
will_bounce	The mailbox doesn't exist, the domain has no mail server, or it's a throwaway address.	Remove it.
unknown	The server didn't give a clear answer. You weren't charged for it.	Leave it out for now.

More detail on each: What each result means.

Errors

Every error has the same shape:

{ "error": { "code": "not_enough_credits", "message": "Not enough credits", "needed": 5000, "available": 1200 } }

Status	code	When
400	invalid_request, invalid_email, no_valid_emails, invalid_group	Something's wrong with what you sent
401	missing_api_key, invalid_api_key	No key, or the key was revoked
402	not_enough_credits	Top up on the pricing page
404	not_found	No list with that id on your account
409	not_ready	Results asked for before the clean finished
413	too_large, too_many_addresses	Split the list
429	rate_limited, free_tier_limit	Slow down. Retry-After says how many seconds

Limits

• 60 single checks a minute per key
• 10 list cleans an hour per key
• 5 cleans a day for accounts that haven't bought credits yet

Need more? Get in touch.

OpenAPI

The full spec is at /openapi.json, if your tools can read OpenAPI.