Agent
Skill

---
name: robotpostal
description: Send physical letters anywhere in the world via API. Use when the user asks to send a letter or physical mail, or when an agent needs to communicate with someone via postal mail. Handles addressing, pricing, payment (x402/MPP/Stripe), order tracking, and proof-of-delivery photos.
license: MIT
metadata:
  author: robotpostal
  version: "1.0"
  website: https://robotpostal.vercel.app
---

# RobotPostal — Physical Mail for AI Agents

Send real physical letters and letters to anyone in the world from the US. You handle the content, we print, envelope, stamp, and mail via USPS.

## When to use this skill

- User asks to send a physical letter or letter
- Agent needs to mail a document, note, or greeting
- User wants to check mail order status or tracking
- User wants to see pricing for sending mail

## API Base URL

```
https://robotpostal.vercel.app/api/v1
```

## Quick Start

### 1. Get a price quote

```bash
curl -X POST https://robotpostal.vercel.app/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{"type": "letter", "pages": 1, "destination": "US"}'
```

Response:
```json
{"postageCents": 73, "markupCents": 15, "totalCents": 88, "currency": "USD"}
```

### 2. Create an order

```bash
curl -X POST https://robotpostal.vercel.app/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "type": "letter",
    "pages": 1,
    "content_format": "plaintext",
    "content_body": "Dear recipient, ...",
    "from": {
      "name": "Sender Name",
      "address1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "to": {
      "name": "Recipient Name",
      "address1": "456 Oak Ave",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    }
  }'
```

Without payment, returns HTTP 402 with x402 payment details. Pay via x402, MPP, or Stripe to complete the order.

### 3. Track an order

```bash
curl https://robotpostal.vercel.app/api/v1/orders/{id}/tracking
```

Returns progress (paid → queued → printed → shipped), timeline, USPS tracking number, and proof photos.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/quote` | Get price quote |
| POST | `/orders` | Create mail order (payment required) |
| GET | `/orders/{id}` | Get order status |
| GET | `/orders/{id}/tracking` | Detailed tracking with timeline & proof photos |
| GET | `/stats` | Public business financials |

## Mail Types

- **letter** — Standard USPS letter, 1-10 pages. Content as plaintext or markdown.
- **postcard** — 4x6 USPS postcard. Single sided.

## Pricing

USPS retail rates + 20% service fee:

| Type | Domestic | International |
|------|----------|---------------|
| Letter (1oz / ~3 pages) | $0.88 | $1.98 |
| Letter additional ounce | $0.34 | $1.02 |
| Postcard | $0.67 | $1.98 |

Always call `/quote` first to get exact pricing.

## Payment Methods

### x402 (recommended)
1. Send order without payment → receive 402 with payment details
2. Pay USDC on Base to the specified address
3. Retry request with `X-PAYMENT` header containing proof

### MPP (Machine Payment Protocol)
1. Send order with `X-PAYMENT-METHOD: mpp` header
2. Complete the MPP payment flow

### Stripe
Include `stripe_token` or `payment_method_id` in the order body.

## Content Formats

- `plaintext` — Plain text, we handle formatting and printing
- `markdown` — Markdown, rendered to print layout

## Address Format

```json
{
  "name": "Required — recipient name",
  "address1": "Required — street address",
  "address2": "Optional — apt, suite, etc",
  "city": "Required",
  "state": "Optional — required for US",
  "zip": "Optional — required for US",
  "country": "Required — 2-letter ISO code (US, GB, JP, etc)"
}
```

## Gotchas

- **PDF upload is not yet supported.** Use plaintext or markdown.
- **Letters max 10 pages.** More than 10 pages requires a different mail class.
- **International addresses** don't require state/zip but do require country code.
- **Idempotency**: Include `idempotency_key` in orders to prevent duplicates.
- **From address must be in the US** — we mail from the United States via USPS.

## OpenAPI Spec

Full spec at: https://robotpostal.vercel.app/openapi.yaml

## Transparency

All business financials are public at `/stats`. Revenue, costs, profit, and investment roadmap — everything is visible. This is an open business.