# BounceLayer — Complete AI Agent & Autonomous System Integration Guide

> Everything an AI agent, LLM workflow, or autonomous agent needs to verify email addresses with BounceLayer.
> Paste this entire document into your agent's system prompt or context window.
> Production Base URL: https://bouncelayer.com/api/v1 (or https://api.bouncelayer.com/v1)
> Web Application: https://bouncelayer.com
> MCP Endpoint: https://bouncelayer.com/mcp

BounceLayer is enterprise-grade, high-throughput email verification infrastructure: real-time single and bulk verification with syntax parsing (RFC 5322), authoritative DNS & MX host resolution, direct TCP port 25 SMTP mailbox handshakes, disposable domain firewalls (100K+ tracked domains), role-based account detection, free-provider classification, and catch-all domain heuristics. Unit-priced credit billing with non-expiring credits; every new account includes 100 free test credits.

---

## 1. Authentication & Security

1. Generate an API key in the BounceLayer dashboard (https://bouncelayer.com/dashboard/api-keys). Live production keys are prefixed with `bl_live_` or `bl_live_`.
2. Include the key on every HTTP request in the `X-API-Key` header:
   ```http
   X-API-Key: bl_live_your_api_key_here
   ```
   Or using Bearer authorization:
   ```http
   Authorization: Bearer bl_live_your_api_key_here
   ```

### Credit Billing Rules
- **1 Credit per verification check**: Deducts 1 credit for all processed emails (`valid`, `invalid`, `catch_all`, `do_not_mail`, `unknown`) to cover dedicated server computation time, live DNS queries, and direct SMTP socket connection probes.
- **0 Credits for Read Operations**: Status polling (`GET /v1/verify/bulk/{job_id}`), job listings, result downloads, and credit balance inquiries are 100% free.
- **Credits Never Expire**: Purchased credits remain valid permanently across all plans.

### Machine-Readable Discovery & Endpoints
- **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`
- **This Guide (Full)**: `https://bouncelayer.com/llms-full.txt`
- **Concise Index**: `https://bouncelayer.com/llms.txt`

---

## 2. Integration Modes

### Option A: Model Context Protocol (MCP) Server (Recommended for AI Agents)

BounceLayer operates an official MCP server over Streamable HTTP transport at `https://bouncelayer.com/mcp`. AI assistants (Cursor, Claude Desktop, Claude Code, Windsurf, Devin) can call verification tools natively.

#### Quick Launcher (stdio or remote clients):
Add to your client configuration (e.g. `claude_desktop_config.json` or `.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "bouncelayer": {
      "command": "npx",
      "args": ["-y", "@bouncelayer/mcp"],
      "env": {
        "BOUNCELAYER_API_KEY": "bl_live_your_api_key_here"
      }
    }
  }
}
```

#### Claude Code Direct Remote Connect:
```bash
claude mcp add --transport http bouncelayer https://bouncelayer.com/mcp/ --header "X-API-Key: bl_live_your_api_key_here"
```

#### MCP Tool Catalog:
- `verify_email(email)`: Real-time 7-layer verification of an individual address. Cost: 1 credit per check.
- `submit_bulk_verification(emails, webhook_url?)`: Submits an asynchronous list of up to 10,000 addresses. Reserves N credits.
- `get_bulk_job(job_id)`: Fetches progress telemetry, valid/invalid breakdown, and completed results array. Free.
- `list_bulk_jobs(page?, page_size?, status?)`: Queries historic batch jobs with pagination. Free.
- `cancel_bulk_job(job_id)`: Cancels pending list processing and immediately refunds unspent reserved credits. Free.
- `get_credit_balance()`: Returns active remaining credit balance and lifetime usage counters. Free.
- `verify_email_demo(email)`: Syntax, MX, disposable, and role verification without live port 25 SMTP handshake. Free (no key required).
- `get_api_discovery()`: Returns machine-readable API routes and OpenAPI specs. Free.

---

### Option B: REST API

Base URL: `https://bouncelayer.com/api/v1` (or `https://api.bouncelayer.com/v1`)

#### 1. Verify Single Email (Real-time)
`POST /api/v1/verify/single` (or `POST /v1/verify/single`)
Headers: `X-API-Key: bl_live_...`, `Content-Type: application/json`
```json
{
  "email": "alex@company.com"
}
```
**Success Response (HTTP 200)**:
```json
{
  "success": true,
  "credits_used": 1,
  "result": {
    "email": "alex@company.com",
    "status": "valid",
    "is_valid": true,
    "syntax_valid": true,
    "domain": "company.com",
    "domain_valid": true,
    "has_mx": true,
    "mx_records": [
      {"priority": 10, "host": "aspmx.l.google.com"}
    ],
    "smtp_checked": true,
    "smtp_response_code": 250,
    "is_disposable": false,
    "is_role_based": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "confidence_score": 98,
    "status_reason": "mailbox_confirmed",
    "provider": "google",
    "verification_time_ms": 142,
    "cached": false
  }
}
```

#### 2. Submit Bulk Verification (Asynchronous)
`POST /api/v1/verify/bulk`
Submits up to 10,000 email addresses for parallel verification with optional HMAC webhook dispatch.
```json
{
  "emails": [
    "sarah@acme.com",
    "john@tempmail.org",
    "info@consulting.co"
  ],
  "webhook_url": "https://yourapp.com/api/webhooks/bouncelayer"
}
```
**Response (HTTP 200/202 Accepted)**:
```json
{
  "job_id": "job_01j8k9m2x5r8p1",
  "status": "pending",
  "total_emails": 3,
  "credits_reserved": 3,
  "created_at": "2026-10-05T10:00:00Z"
}
```

#### 3. Poll Bulk Job Status
`GET /api/v1/verify/bulk/{job_id}` — Free
Returns status (`pending`, `processing`, `completed`, `cancelled`), progress percentage, counts, and the array of `VerificationResult` objects once completed.

#### 4. Cancel Bulk Job
`DELETE /api/v1/verify/bulk/{job_id}` — Free
Cancels processing and instantly releases reserved credits back to the account.

#### 5. Export Verification Results
`GET /api/v1/verify/bulk/{job_id}/download?format=json|csv` — Free

#### 6. Check Credit Balance
`GET /api/v1/credits` — Free
```json
{
  "balance": 24950,
  "lifetime_used": 158200
}
```

#### 7. Ingest Bounce Telemetry (Improves Accuracy)
`POST /api/v1/webhooks/bounce` — Free
```json
{
  "events": [
    {
      "email": "bad@olddomain.com",
      "event_type": "hard_bounce",
      "bounce_code": "550",
      "bounce_message": "User unknown",
      "timestamp": "2026-10-05T10:30:00Z"
    }
  ]
}
```

---

## 3. The VerificationResult Data Schema

| Field | Type | Description |
|---|---|---|
| `email` | `string` | Lowercased, sanitized email address evaluated |
| `status` | `string` | Primary verdict: `valid`, `invalid`, `catch_all`, `unknown`, `do_not_mail` |
| `is_valid` | `boolean` | Quick boolean flag: `true` if safe to send, `false` otherwise |
| `syntax_valid` | `boolean` | RFC 5322 syntax and regex formatting check |
| `domain` | `string` | Extracted domain component |
| `domain_valid` | `boolean` | Authoritative DNS A/AAAA record resolution |
| `has_mx` | `boolean` | Confirmed Mail Exchange (MX) DNS records present |
| `mx_records` | `array` | List of MX hosts with priority weights |
| `smtp_checked` | `boolean` | Indicates whether live TCP port 25 socket probe was executed |
| `smtp_response_code` | `integer\|null` | Standard RFC 5321 SMTP reply code (e.g. 250, 550, 451) |
| `is_disposable` | `boolean` | Matches 100K+ temporary/burner domain database |
| `is_role_based` | `boolean` | Generic organizational mailbox (e.g. billing@, support@, admin@) |
| `is_catch_all` | `boolean` | Domain configured to receive all incoming mail regardless of mailbox |
| `is_free_provider` | `boolean` | Public ESP consumer mailbox (Gmail, Yahoo, Hotmail, etc.) |
| `confidence_score` | `integer` | Normalized deliverability score (0 to 100) |
| `status_reason` | `string` | Granular programmatic diagnosis reason |
| `provider` | `string\|null` | Identified enterprise mail infrastructure (e.g. `google`, `microsoft`) |
| `verification_time_ms`| `number` | Total socket roundtrip and evaluation latency in milliseconds |
| `cached` | `boolean` | Indicates if result was served from 7-day high-speed verification cache |

---

## 4. Status Reason Reference Matrix

| Status Reason | Primary Status | Explanation | Recommended Action |
|---|---|---|---|
| `mailbox_confirmed` | `valid` | SMTP remote host returned `250 OK` for recipient | Safe to send |
| `mailbox_not_found` | `invalid` | SMTP remote host returned `550 User Unknown` | Do not send (will bounce) |
| `failed_syntax_check` | `invalid` | Malformed address failing RFC 5322 | Drop from list |
| `no_dns_entries` | `invalid` | Domain name does not exist in public DNS | Drop from list |
| `no_mx_records` | `invalid` | Domain exists but has no mail routing records | Drop from list |
| `disposable` | `do_not_mail` | Throwaway burner service (e.g. 10minutemail) | Reject registration |
| `role_based` | `do_not_mail` | Shared organizational address (admin@, sales@) | Lower priority |
| `accept_all` | `catch_all` | Domain accepts any random mailbox test | Send with warm IP only |
| `antispam_system` | `unknown` | Remote MTA blocked probe or requires human challenge | 1 credit billed (Computation) |
| `failed_smtp_connection`| `unknown` | TCP port 25 connection timed out | 1 credit billed (Computation) |
| `greylisting` | `unknown` | Remote MTA deferred connection per greylist policy | Retry after 15 mins |
| `mail_server_temporary_error`| `unknown` | Remote server returned `4xx` transient error | 1 credit billed (Computation) |

---

## 5. HTTP Error Handling & Status Codes

- `401 Unauthorized`: API key is missing or invalid. Verify `X-API-Key` header.
- `402 Payment Required`: Insufficient credit balance. Top-up credits or activate plan.
- `404 Not Found`: Bulk job ID or requested resource does not exist.
- `413 Payload Too Large`: Bulk payload exceeds max batch limit (10,000 emails).
- `422 Unprocessable Entity`: Request JSON payload failed validation schema.
- `429 Too Many Requests`: Rate limit exceeded. Back off according to `Retry-After` header.

---

## 6. Machine-Readable Discovery Endpoints
- OpenAPI 3.1 Spec: `https://bouncelayer.com/api/public-openapi.json`
- MCP Server Discovery: `https://bouncelayer.com/.well-known/mcp.json`
- MCP Server Card: `https://bouncelayer.com/.well-known/mcp/server-card.json`
- LLM Quick Guide: `https://bouncelayer.com/llms.txt`
- Full LLM Documentation: `https://bouncelayer.com/llms-full.txt`
- Interactive Developer Portal: `https://bouncelayer.com/docs`