API keys

An API key lets your own code, or an AI assistant connected over MCP, check addresses with your BounceOwl credits. You create and revoke keys on the API & MCP page.

Create a key

1. Open API & MCP from the sidebar.
2. Under API keys, type a name that tells you where the key will be used, such as the app or teammate it is for.
3. Click Create key.
4. A panel titled Copy your new key now shows the full key. Copy it and store it somewhere safe, such as your password manager or your app's secret settings.
5. Click I saved it.

The full key is shown only once. After you close the panel, BounceOwl shows just the start of the key, so you can tell keys apart. If you lose a key, revoke it and create another.

One key per app

Create a separate key for each app, script, AI assistant or teammate. Then if one of them no longer needs access, you can revoke just that key and everything else keeps working. The key list shows each key's name and when it was last used, or Never used.

Use the key

Send the key as a Bearer token in the Authorization header. The base URL is https://api.bounceowl.com. To check one address:

curl https://api.bounceowl.com/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "name@company.com"}'

A few things to know:

• POST /v1/verify answers in the same request. Set your client timeout to 150 seconds, because slow mail servers can take a while.
• The default limit is 300 verify calls per minute per key.
• When you run out of credits, the API returns status 402 with the credits needed and your current balance.
• Other endpoints cover lists (POST /v1/bulk), catch-all checks (POST /v1/catchall) and prices (GET /v1/pricing).

Checks made with a key cost the same as checks in the app, and they appear in History with API in the From column. The full reference is in the API docs.

Revoke a key

1. Open API & MCP.
2. Find the key by its name in the list.
3. Click Revoke.

Apps using that key stop working right away. Revoke a key whenever it may have been shared by mistake, or when the app or person using it no longer needs access.

Keep keys private

• Don't put a key in a public code repository or in code that runs in a browser.
• Anyone with the key can use your credits, so treat it like a password.

Related

• Connect an AI assistant
• API docs