# Paper Owl Mail: agent brief

Read this file first. It is the contract for using Paper Owl Mail from an agent.

Paper Owl Mail prints and mails one letter to one US address (the 50 states and DC), as a First-Class letter or USPS Certified Mail. The user always sees every page, both addresses and the price, and approves the charge, before anything is printed. A paid letter can be cancelled for a full refund for 15 minutes.

## Connection

| Field | Value |
| --- | --- |
| Product | Paper Owl Mail |
| Developer | Vectis Studio LLC |
| Website | https://sendpaperowl.com |
| MCP endpoint | https://api.sendpaperowl.com/mail/mcp |
| Transport | Streamable HTTP, POST only, JSON responses (no SSE), stateless (no sessions) |
| Protocol | 2026-07-28 (per-request `_meta`), and 2025-06-18 / 2025-11-25 clients that send `initialize` |
| Auth | None. Payment approval is the user's consent for the write. Draft IDs are unguessable. |
| REST API | https://api.sendpaperowl.com/mail/v1 (OpenAPI: https://api.sendpaperowl.com/mail/openapi.json) |
| Docs | https://api.sendpaperowl.com/mail/docs |
| llms.txt | https://api.sendpaperowl.com/mail/llms.txt |
| Terms | https://sendpaperowl.com/legal/terms#mail |
| Privacy | https://sendpaperowl.com/legal/privacy#mail |
| Support | support@sendpaperowl.com |
| Rate limits | 1200 requests per minute per IP; 200 drafts per hour per IP; at most 2 letters a day and 5 a week to one address, from all senders. The test path allows 25 test letters a day in total and 3 per payer. Other paid letters: at most 10 a day in total and 3 per payer |

## Flow

1. Ask the user for their own name and return address (a US address where they receive mail), the recipient's name and address, the letter (or what to write), and the service: `first_class`, `certified` or `certified_return_receipt`.
2. Call `create_mail_draft`.
3. Show the user both addresses as they will print, and any `address_changes` USPS standardization made, the service, the pages and the price. Read `payment_terms` word for word and offer `preview_url`.
4. Then one of:
   - **In-chat payment (Muse):** ask the user to approve the exact price and to confirm they are the sender named on the letter, or authorized to send for the business named on the letter, the return address is where that sender receives mail, and the letter is not advertising, a bill-like solicitation, debt collection or political campaign mail. Call `send_mail` with the `draft_id`, the granted Stripe shared payment token (`spt_...`) as `payment_token`, and `attest_sender_and_content: true`.
   - **No in-chat payment:** give the user `review_url`. They check the letter, tick the box and pay with Stripe Checkout.
5. The letter is held 15 minutes; `cancel_mail` during that time refunds it in full. Then it goes to print. Call `get_mail_status` about once a day after that and relay `next_step`.

## Testing (reviewers)

Address a letter to the recipient name **Paper Owl Mail Test Desk**, at any US address. It runs the normal paid flow, goes to our printer in test mode (a real proof, never printed or mailed), and the charge is refunded in full automatically once the hold ends. Limits: 25 test letters a day in total and 3 per payer.

Cancelling during the 15-minute hold (cancel_mail, or the button on the review page) refunds the charge at once, so the cancel path can be tried too.

## Tools

| Tool | When | Key inputs |
| --- | --- | --- |
| `create_mail_draft` | The user wants to mail a letter. Always first. | from, to, service, and one of text, pdf_base64, pdf_url |
| `send_mail` | The user approved the exact price in chat and confirmed the sender and content. | draft_id, payment_token, attest_sender_and_content: true |
| `get_mail_status` | After paying, to follow the letter. | draft_id |
| `cancel_mail` | Before paying, or within the hold after paying. | draft_id |

## Prices

- First-Class letter: $2.99 covers up to 3 pages, plus $0.25 for each page after that, up to 5 pages.
- Certified Mail: $10.99 covers up to 3 pages, plus $0.25 for each page after that, up to 5 pages.
- Certified Mail with electronic return receipt: $13.99 covers up to 3 pages, plus $0.25 for each page after that, up to 5 pages.
- Letters are black and white, single-sided, at most 5 pages. A Certified Mail letter from a PDF can be at most 4 pages.

Payment terms: First-Class letter $2.99, Certified Mail $10.99, Certified Mail with electronic return receipt $13.99; each covers up to 3 pages, plus $0.25 for each page after that, up to 5 pages; a Certified Mail letter from a PDF can be up to 4 pages. The user is charged only when they approve the exact total. A paid letter can be cancelled for a full refund for 15 minutes, then it goes to print. If the printer rejects a letter, the full price is refunded automatically. A letter that has reached USPS is not refundable, including one USPS returns. An unpaid draft can be cancelled free at any time and expires after 24 hours.

## Will not

- Mail to more than one address, or outside the 50 states and DC.
- Mail advertising, bulk mail, bill-like solicitations, government look-alikes, sweepstakes, debt collection or political campaign mail.