API Documentation - Mailroom Agent

Quick Start

Get started in three simple steps.

1

Get Your API Key

Create an API key from the Console.

2

Encode Your PDF

Base64 encode your PDF document.

3

Send Request

POST to the classify endpoint and get structured JSON back.

cURL

# Encode PDF and send to API
curl -X POST https://api.mailroomagent.com/v1/classify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "'$(base64 -i document.pdf)'",
    "options": {
      "extract_dates": true,
      "extract_adj": true
    }
  }'

Endpoints

POST /v1/classify

Classify a document and extract structured data.

Request Headers

`Authorization`	Bearer YOUR_API_KEY	Required
`Content-Type`	application/json	Required

Request Body

`document`	Base64 encoded PDF content	Required
`document_type`	File type (default: "pdf")	Optional
`options.extract_dates`	Extract dates (default: false)	Optional
`options.extract_adj`	Extract ADJ numbers (default: false)	Optional
`cases`	Array of case objects with `adj_number`, `claimant_name`, and `employer` for matching	Optional
`activity_types`	Array of activity type strings for classification	Optional

Example Request

{
  "document": "JVBERi0xLjQK...",
  "document_type": "pdf",
  "options": {
    "extract_dates": true,
    "extract_adj": true
  }
}

POST /v1/analyze-batch

Analyze a batch-scanned PDF containing multiple documents separated by barcode separator sheets.

Request Body

`document`	Base64 encoded batch PDF	Required
`cases`	Array of case objects with `adj_number`, `claimant_name`, and `employer` fields for matching	Optional
`activity_types`	Array of activity type strings for classification (e.g., "Notice of Hearing", "Medical Report", "Correspondence")	Optional

Example Response

{
  "success": true,
  "data": {
    "separator_pages": [4, 8, 12],
    "documents": [
      {
        "start_page": 1,
        "end_page": 3,
        "doc_type": "Notice of Hearing",
        "applicant_name": "John Smith",
        "adj_numbers": ["ADJ13226857"],
        "document_date": "20260122",
        "suggested_filename": "20260122-notice-of-hearing-smith",
        "calendar_dates": [
          {
            "date": "2026-02-15",
            "time": "09:30",
            "type": "hearing",
            "location": "123 Main St, Riverside CA"
          }
        ]
      }
    ]
  }
}

GET /health

Check API health status.

// Response
{
  "status": "ok",
  "timestamp": "2026-02-02T18:30:00Z"
}

Rate Limits

Trial	100 requests/day, 60 requests/minute burst
Pro	1,000 requests/day, 300 requests/minute burst
Enterprise	10,000 requests/day, 1,000 requests/minute burst

Daily limits reset at midnight UTC. Rate limit headers are included in all API responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Pro plans also enforce a 10,000 requests/month quota via X-Quota-* headers.

MCP Integration

Connect Mailroom Agent directly to Claude Code as an MCP server.

1. Add to Claude Code Settings

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "mailroom": {
      "type": "url",
      "url": "https://api.mailroomagent.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

2. Available Tools

`classify_document`	Classify document from base64 content
`classify_file`	Classify document from file path

3. Example Usage

# In Claude Code, just ask:

> Classify this PDF: /path/to/document.pdf

> What type of document is this and extract the hearing dates

> Extract all ADJ numbers from this legal document

Response Format

{
  "success": true,
  "data": {
    "document_type": "wcab_form",
    "confidence": 0.95,
    "summary": "Notice of Hearing from WCAB...",
    "page_count": 6,
    "parties": ["ANA GUEVARA", "ASCENA RETAIL GROUP"],
    "case_numbers": ["ADJ13226857"],
    "dates": [
      {
        "date": "2026-01-22",
        "type": "hearing",
        "description": "Date of Hearing",
        "location": "3737 MAIN ST, RIVERSIDE CA"
      }
    ],
    "adj_numbers": [
      {
        "number": "ADJ13226857",
        "claimant_name": "ANA GUEVARA",
        "employer": "ASCENA RETAIL GROUP INC"
      }
    ]
  }
}

Document Types

medical_report wcab_form correspondence deposition subpoena court_order billing unknown

Date Types

hearing deadline appointment trial injury other

Error Codes

`400`	Bad Request - Invalid request body or missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - API key lacks required permissions
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

// Error Response
{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}

Ready to Get Started?

Create your API key and start classifying documents in minutes.

Get API Key