Mailclaw API

Send a PDF or plain text via USPS. Pay with Solana USDC.

Machine-readable spec

Public API

No authentication required. All endpoints are public and rate-limited to 10 requests per minute per IP.

Base URL

https://mailclaw.xyz

Endpoints

GET/api/v1/health

Health check. Returns service status.

GET/api/v1/pricing

Get current pricing configuration.

POST/api/v1/preview

Preview page count and pricing before creating a job. Send a content object (PDF or text) and a service type.

Request

{
  "content": {
    "text": "Dear Gabe, it has been 19 years. We just want to know: is Half-Life 3 coming or not? Please respond via certified mail. Sincerely, Everyone."
  },
  "service": "certified"
}

Response

{
  "pageCount": 1,
  "pricing": {
    "totalUsd": 9.4,
    "totalUsdc": "9400000",
    "breakdown": {
      "basePrice": 9.4,
      "extraPageCost": 0
    }
  }
}

POST/api/v1/jobs

Create a mail job. Submit a PDF or plain text with to/from addresses, email, and service type. Returns a Solana deposit address and USDC amount. After payment, the document is printed and mailed. Payment window is 30 minutes.

Request

{
  "email": "impatient_gamer@example.com",
  "to": {
    "name": "Gabe Newell",
    "address_line1": "10400 NE 4th St",
    "address_city": "Bellevue",
    "address_state": "WA",
    "address_zip": "98004"
  },
  "from": {
    "name": "Everyone",
    "address_line1": "1 Internet Blvd",
    "address_city": "The World",
    "address_state": "CA",
    "address_zip": "90210"
  },
  "content": {
    "text": "Dear Gabe, it has been 19 years. We just want to know: is Half-Life 3 coming or not? Please respond via certified mail. Sincerely, Everyone."
  },
  "service": "certified"
}

Response

{
  "id": "job_abc123",
  "status": "awaiting_payment",
  "service": "certified",
  "message": "Job created. Pay to send.",
  "payment": {
    "address": "SolanaAddress...",
    "amount": "9400000",
    "amountUsd": 9.4,
    "network": "solana-mainnet",
    "token": "USDC",
    "expiresAt": "2026-02-15T12:30:00Z"
  },
  "pageCount": 1
}

GET/api/v1/jobs/:id

Get job status, service type, payment info, envelope photo URL, and tracking number (if certified).

GET/api/v1/jobs/:id/document

Download the rendered PDF document for a job.

POST/api/v1/jobs/:id/cancel

Cancel an unpaid job (only works while status is awaiting_payment).

Content Object

Provide one of the following in the content field:

content.pdfstringBase64-encoded PDF file

content.textstringPlain text content (rendered to PDF for printing)

Exactly one of pdf or text must be provided.

Service Types

Value	Description	Price
`first_class`	USPS First Class (domestic)	$4.80
`certified`	Certified Mail (domestic, default)	$9.40
`certified_return_receipt`	Certified + Return Receipt	$16.00
`international`	International First Class	$9.45

All services include 3 pages. Additional pages are +$1.00 each.

Job Status Flow

awaiting_paymentCreated, waiting for USDC payment

pending_reviewPayment received, queued for printing

processingBeing printed and prepared

shippedMailed, tracking entered (if certified)

deliveredConfirmed delivered

rejectedRejected, payment forfeited

cancelledCancelled by user before payment

expiredPayment window expired (30 min)

Payment

Create a job via POST /api/v1/jobs with your content and addresses
Send the exact USDC amount to the provided Solana address within 30 minutes
Payment is detected automatically
Your document is printed, the envelope is hand-addressed, and it is mailed via USPS
Track status via GET /api/v1/jobs/:id

An email address is required with every order. You will receive status updates at the provided email.

Payment network: Solana Mainnet. USDC mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Pricing

USPS First Class (domestic): $4.80

Certified Mail (domestic): $9.40

Certified + Return Receipt: $16.00

International First Class: $9.45

Extra pages (beyond 3): +$1.00/page

All prices in USD, paid as USDC on Solana.

Error Codes

400BAD_REQUESTInvalid request parameters

404NOT_FOUNDResource not found

429RATE_LIMITRate limit exceeded

500INTERNAL_ERRORServer error