postagent-print-and-mail

# PostAgent — Print & Mail

PostAgent turns a digital document into **physical mail** that is printed and
delivered via USPS. You upload a document, lock a price quote, and pay per send
with the [x402](https://www.x402.org/) payment protocol (USDC on Base mainnet).
PostAgent then hands the job to [Lob](https://www.lob.com/) for printing and
USPS delivery.

Products:

- **Letters** — PDF/HTML/Markdown/text/DOCX/image, optional color, certified /
  certified-with-return-receipt / registered mail.
- **Postcards** — 4x6 / 6x9 / 6x11, full color, from front+back artwork
  (4x6 cards can ship internationally).
- **Address verification** — standalone paid deliverability check (US CASS or
  international), ~2¢ per call.
- **Bulk campaigns** — one creative, up to 500 recipients, via the provider's
  campaign pipeline. **KYC-walled: unavailable until identity verification
  launches** (see [Bulk campaigns](#bulk-campaigns-kyc-required)).

- **Service base URL:** `https://postagent-api.interpretai.tech`
- **MCP endpoint:** `https://postagent-api.interpretai.tech/mcp`

## When to use this skill

Use it when the user wants to **send real physical mail in the US**, e.g.:

- "Mail this PDF letter to 500 Market St, San Francisco."
- "Send a printed notice to these 10 customers."
- "Post this invoice to my client." / "Send it certified with return receipt."
- "Mail a postcard to…" / "Is this address deliverable?"

Do **not** use it for email, faxes, or packages/parcels. International delivery
is supported **only** for 4x6 postcards; all letters are US-to-US.

## CRITICAL — read before sending

- **Real money + irreversible.** Submitting a paid job charges USDC and prints &
  mails a physical piece. It cannot be undone. **Always** show the user the
  recipient, sender, page count, and price, and get **explicit confirmation**
  before paying.
- **US senders + US recipients** for letters. State must be a 2-letter code
  (e.g. `CA`); ZIP must be 5-digit or ZIP+4. Exception: a **4x6 postcard** may
  go to an international recipient (set `to.country` to the 2-letter ISO code);
  the sender must still be a US address.
- **Non-custodial payment.** PostAgent never holds a wallet. The agent's own
  x402-capable wallet (or a Shared Payment Token it mints) must sign and pay the
  quote — never fabricate payment. If you have no payment method yet, don't just
  fall back to hosted checkout: pick a rail and set one up (see
  [Payment methods & setup](#payment-methods--setup) below).
- **One letter = one quote + one payment + one job.** There is no batch send. To
  mail N recipients, repeat the quote→pay→job cycle N times (you can reuse the
  same `documentId`).

## How to call PostAgent

Drive the **REST/HTTP API** directly — this works in any agent with shell or
HTTP access and needs no setup, so it is the default path used throughout this
skill. If the PostAgent **MCP server** happens to be configured in your client,
you may use its structured tools instead (they map 1:1 to these steps); see
[Optional: MCP server](#optional-mcp-server) at the end. Either way, payment is
the same non-custodial x402 step (the API never signs for you).

## Workflow

### 1. Upload the document (free)

A document is either a **finished letter** (the stored PDF is mailed as-is) or a
**mail-merge template** (`{{field}}` placeholders filled per recipient).

REST — finished letter from inline Markdown:

```bash
curl -sX POST https://postagent-api.interpretai.tech/v1/documents \
  -H "content-type: application/json" \
  -d '{ "format": "markdown", "content": "# Notice\n\nPlease review the attached terms.", "template": false }'
```

REST — finished letter from an existing PDF (base64 or URL):

```bash
curl -sX POST https://postagent-api.interpretai.tech/v1/documents \
  -H "content-type: application/json" \
  -d '{ "format": "pdf", "url": "https://example.com/letter.pdf", "template": false }'
```

REST — reusable template (must be text-based and contain at least one `{{field}}`):

```bash
curl -sX POST https://postagent-api.interpretai.tech/v1/documents \
  -H "content-type: application/json" \
  -d '{ "format": "html", "content": "<p>Dear {{name}}, your balance is {{amount}}.</p>", "template": true }'
```

Accepted formats: `pdf`, `html`, `markdown`, `text`, `docx`, `image` (PNG/JPEG).
Provide content exactly one way: inline `content` (text formats), `contentBase64`
(binary), or `url`. The response returns a `documentId` (e.g. `doc_...`), the
page count, and — for templates — the detected `mergeFields`.

> **Images / pictures.** To mail a picture *as the letter*, upload it with
> `format: "image"` (PNG/JPEG via `contentBase64` or `url`). To place a picture
> *inline* in an `html`/`markdown` letter, it MUST be embedded as a base64 data
> URI (e.g. `<img src="data:image/png;base64,iVBORw0KGgo...">` or
> `![](data:image/png;base64,...)`). External image URLs such as
> `<img src="https://...">` are **blocked and render blank** — the PDF renderer
> runs with no network access for security, so only `data:` images load.
> Already have a composed image-bearing document? Send it as `format: "pdf"`.

Easiest way to mail a standalone picture — pass a `url` and the **server**
fetches it (no base64 needed):

```bash
curl -sX POST https://postagent-api.interpretai.tech/v1/documents \
  -H "content-type: application/json" \
  -d '{ "format": "image", "url": "https://example.com/photo.png", "template": false }'
```

To inline a **local** image inside an html/markdown letter, encode it to a
base64 data URI and send the request body **from a file** — a real image's
base64 is far too large to place on the command line:

```bash
# 1. Encode the image into a data URI (one long line, no newlines).
IMG="data:image/png;base64,$(base64 -i logo.png | tr -d '\n')"
# 2. Write the JSON body to a file so the big blob never hits the shell args.
cat > body.json <<JSON
{ "format": "html", "template": false,
  "content": "<h1>Hello</h1><img src=\"$IMG\" style=\"max-width:400p