# Quickstart

> Make your first isBusinessEmail API call in 30 seconds with curl, JavaScript or Python, then switch from test addresses to a real key.

Source: https://isbusinessemail.com/docs/quickstart

## 1. Try it without a key

Addresses under `test.isbusinessemail.com` return fixed results, need no key and never count toward a quota:

```bash
curl -sG https://api.isbusinessemail.com/v1/check \
  --data-urlencode "email=workspace@test.isbusinessemail.com"
```

You get the full response shape, including `category`, `recommendation`, `reasons` and the `workspace` block. All test addresses are listed in [Test addresses](https://isbusinessemail.com/docs/test-addresses).

## 2. Get a free key

[Sign up](https://isbusinessemail.com/signup) with Google, Microsoft or a magic link. Your first secret key (`ibe_live_…`) is created automatically and shown **once**, so copy it into your secret manager or `.env`:

```bash
export IBE_API_KEY="ibe_live_…"
```

## 3. Check a real address

Use `POST` so addresses don't end up in URLs, proxy logs or browser history.

### curl

```bash
curl -s https://api.isbusinessemail.com/v1/check \
  -H "Authorization: Bearer $IBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.io"}'
```

### JavaScript (Node 18+, Deno, Bun, Workers)

```javascript
const res = await fetch('https://api.isbusinessemail.com/v1/check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IBE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'jane@acme.io' }),
  signal: AbortSignal.timeout(2500),
});
const result = await res.json();
console.log(result.category, result.recommendation, result.reasons);
```

### Python

```python
import os
import requests

r = requests.post(
    "https://api.isbusinessemail.com/v1/check",
    json={"email": "jane@acme.io"},
    headers={"Authorization": f"Bearer {os.environ['IBE_API_KEY']}"},
    timeout=3,
)
r.raise_for_status()
result = r.json()
print(result["category"], result["recommendation"], result["reasons"])
```

## 4. Act on the result

The one field most integrations need is `recommendation`:

| `recommendation` | Typical action |
|---|---|
| `allow` | Continue the signup |
| `review` | Let them in, but flag the account (manual check, email verification, shorter trial) |
| `block` | Ask for a work email; show `did_you_mean` if present |

The default policy is `b2b`. Pass `policy=strict` or `policy=lenient` to change what gets blocked; see [Categories and policies](https://isbusinessemail.com/docs/categories-and-policies).

## 5. Ship it safely

- **Fail open.** If the call times out or returns `5xx`/`429`, let the signup through and re-check later. Never make our uptime your signup's uptime.
- **Keep the key on the server.** For browser-side hints, use a [publishable key](https://isbusinessemail.com/docs/authentication#publishable-keys) restricted to your domain.
- **Store the verdict, not the address.** Save `category`, `recommendation` and `reasons` on the account for analytics and routing.

Next: [Authentication](https://isbusinessemail.com/docs/authentication) · [Response fields](https://isbusinessemail.com/docs/response-fields) · [Signup form guide](https://isbusinessemail.com/docs/signup-form-guide) · [More languages](https://isbusinessemail.com/docs/code-examples)