# Scrubby Email Validation API - Full Technical Reference Scrubby provides advanced email validation for catch-all and high-risk emails. This document is optimized for LLMs to understand and integrate with the Scrubby API. ## API Fundamentals - **Base URL**: `https://system.scrubby.io` - **Authentication**: Header `x-api-key: YOUR_KEY` (also accepts `Authorization: Api-Key YOUR_KEY`). - **Rate Limit**: 25 requests per second (1500 requests per minute) per API key. Returns HTTP 429 if exceeded. - **Support**: High-performance validation for "catch-all" (accept-all) domains. --- ## Validation Workflows ### 1. Single Email Validation (Real-time) Used for immediate feedback (e.g., signup forms). - **Endpoint**: `POST /validate_email` - **Behavior**: Returns result immediately. 15s timeout. ### 2. Bulk Email Validation (Asynchronous) Used for large lists. Follows a 3-step process: 1. **Submit**: `POST /validate_bulk_emails` with a list of emails. Receive an `identifier`. 2. **Wait**: Recommended initial wait time is 30 seconds. 3. **Fetch**: `POST /fetch_bulk_results` with the `identifier`. - If `status: processing`, wait 30-60s and retry. - If `status: completed`, all results are ready. --- ## Endpoint Details ### [POST] /validate_email Validate a single email address. - **Request Body**: `{"email": "user@example.com"}` - **Success (200)**: - `email`: Validated email. - `result`: `Valid`, `Invalid`, `Risky`, or `Unknown`. - `status`: Detailed code (e.g., `OK`, `HARD_BOUNCE`). - `quick_status`: `OK`, `HARD_BOUNCE`, `SOFT_BOUNCE`, or `UNKNOWN`. - `credits_used`: Integer count. - **Errors**: 400 (Invalid/No Credits), 408 (Timeout), 429 (Rate Limit). ### [POST] /validate_bulk_emails Queue multiple emails for validation. - **Request Body**: `{"email": ["user1@example.com", "user2@example.com"]}` - **Success (202)**: - `status`: `processing` - `identifier`: Unique string for fetching results. - `retry_after_seconds`: Recommended wait time before fetching (default 30). - `total`: Total emails queued. ### [POST] /fetch_bulk_results Retrieve results for a submitted batch. - **Request Body**: `{"identifier": "batch_id_here"}` - **Success (200)**: - `status`: `processing` or `completed`. - `results`: Map of `email` to `BulkResultItem`. - **BulkResultItem**: - `result`: `Valid`, `Invalid`, `Risky`, `Unknown`, or `pending`. - `status`: Detailed code. - `quick_status`: Simplified label. --- ## Status Definitions - **Valid / OK**: Safe to send. Highly likely to deliver. - **Invalid / HARD_BOUNCE**: Do not send. Email does not exist or is blocked. - **Risky / SOFT_BOUNCE**: Deliverable but may flag as spam or has high risk of bounce. - **Unknown / UNKNOWN**: System could not determine the status within timeout. --- ## Error Handling - **400 Bad Request**: Invalid email format or zero credit balance. - **404 Not Found**: Batch identifier expired or incorrect. - **408 Request Timeout**: Single validation took >15s (credits are refunded). - **429 Rate Limit**: Too many requests. Implementation should use exponential backoff or a brief delay. For any integration help, visit [docs.scrubby.io](https://docs.scrubby.io).