# BounceLayer — AI Agent & Developer Quick Reference

> Canonical reference for AI coding assistants, autonomous agents, and developers.
> Base API URL: https://bouncelayer.com/api/v1 (or https://api.bouncelayer.com/v1)
> MCP Server: https://bouncelayer.com/mcp
> Full Guide: https://bouncelayer.com/llms-full.txt

BounceLayer is high-throughput email verification infrastructure: real-time single and bulk verification with direct TCP port 25 SMTP mailbox handshakes, DNS MX resolution, and disposable domain filtering in <150ms. Pay-as-you-go and recurring monthly plans; 100 free test credits on signup. Credits never expire.

## Machine-Readable Discovery & Specs
- Public OpenAPI spec: https://bouncelayer.com/api/public-openapi.json
- MCP discovery: https://bouncelayer.com/.well-known/mcp.json
- MCP server card: https://bouncelayer.com/.well-known/mcp/server-card.json
- Complete AI Guide: https://bouncelayer.com/llms-full.txt
- Concise Index: https://bouncelayer.com/llms.txt

## Core Endpoints
- `POST /api/v1/verify/single` — Verify 1 email (1 credit per check).
- `POST /api/v1/verify/bulk` — Async bulk verification up to 10,000 emails per job with optional webhook.
- `GET /api/v1/verify/bulk/{job_id}` — Polling job status & full results. Free.
- `GET /api/v1/verify/bulk` — List jobs with pagination. Free.
- `DELETE /api/v1/verify/bulk/{job_id}` — Cancel pending bulk job & release reserved credits. Free.
- `GET /api/v1/verify/bulk/{job_id}/download?format=json|csv` — Export verified lists. Free.
- `GET /api/v1/credits` — Balance & usage telemetry. Free.
- `GET /api/v1/credits/history` — Balance transactions ledger. Free.
- `POST /api/v1/webhooks/bounce` — Ingest delivery/bounce telemetry. Free.
- `GET /api/v1/intelligence/risk` — Domain & email threat risk signals. Free.
- `POST /api/demo/verify` — Public instant validator (no API key required). Free.

## Authentication
Pass your secret API key in the `X-API-Key` header (e.g. `X-API-Key: bl_live_...`) or `Authorization: Bearer bl_live_...`.

## AI Agent MCP Server
- Launch via NPX: `npx -y @bouncelayer/mcp` with env `BOUNCELAYER_API_KEY=bl_live_...`
- Direct HTTP stream: `claude mcp add --transport http bouncelayer https://bouncelayer.com/mcp/ --header "X-API-Key: bl_live_..."`
- Tools: `verify_email`, `submit_bulk_verification`, `get_bulk_job`, `list_bulk_jobs`, `cancel_bulk_job`, `get_credit_balance`, `verify_email_demo`.

## Statuses
- `valid`: Confirmed deliverable mailbox via SMTP 250 OK.
- `invalid`: Rejected mailbox (SMTP 550), invalid domain, or RFC syntax failure.
- `catch_all`: Domain accepts all mail; individual mailbox cannot be definitively isolated.
- `unknown`: Server timed out or anti-spam throttled. 0 credits billed (100% Free).
- `do_not_mail`: High-risk address (disposable burner or role account).