---
title: Quickstart
slug: developers.mailfloss.com
docTags: 
createdAt: 2026-06-02T04:03:27.751Z
---

Verify your first email address with the mailfloss API in under five minutes.

:::hint{type="info"}
**This is the current mailfloss API (v1).** The original email-verification API (`api.mailfloss.com/verify?api_key=…`) is now deprecated and will **sunset on June 1, 2027**. Build new integrations on v1, and plan to migrate existing ones — see [Authentication](authentication) for the `api_key` → Bearer change.
:::

## 1. Get your API key

Your API key lives in the mailfloss dashboard under **Settings → API**. It's a
secret — treat it like a password, keep it server-side, and never embed it in
client-side code or commit it to source control.

## 2. Verify a single email

Send your key as a Bearer token and call `GET /v1/verify`:

```bash
curl https://api.mailfloss.com/v1/verify?email=test@example.com \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A successful call returns the verdict directly as the response body:

```json
{
  "email": "test@example.com",
  "status": "passed",
  "reason": "valid",
  "passed": true
}
```

- `status` — the deliverability verdict for the address: `passed`,
  `undeliverable`, `risky`, or `unknown`.
- `reason` — the specific signal behind the verdict.
- `passed` — a convenience boolean for "safe to send."

Each successful verification consumes one credit from your account. See the
API reference for the full list of `status` and `reason` values.

## 3. Handle errors

Errors come back in a consistent envelope — branch on the stable `code`, never
on the human-readable `message`:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account is out of verification credits.",
    "type": "billing_error",
    "request_id": "req_a1b2c3"
  }
}
```

Full details in the **Errors** guide.

## 4. Verify in bulk

For lists, submit a batch job and poll for results:

```bash
# Submit
curl -X POST https://api.mailfloss.com/v1/batch-verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["a@example.com", "b@example.com"] }'
# -> { "id": "job_123", ... }

# Poll status
curl https://api.mailfloss.com/v1/batch-verify/job_123/status \
  -H "Authorization: Bearer YOUR_API_KEY"

# Fetch results (paginated) once status is "completed"
curl https://api.mailfloss.com/v1/batch-verify/job_123/results \
  -H "Authorization: Bearer YOUR_API_KEY"
```

POST endpoints accept an optional `Idempotency-Key` header so a retried submit
never double-charges. See the reference for the batch request shape.

## Next steps

- **Authentication** — Bearer vs. the legacy `api_key` parameter, and key handling.
- **Pagination** — how list responses page.
- **Connect an ESP** — verify-first automation across 18 email platforms.
- **SDKs** — official typed clients for Node.js, Python, Ruby, and Go.
- **API reference** — every endpoint, parameter, and response shape.