# Paper Owl Fax: agent brief

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

Paper Owl Fax sends one fax to one US or Canadian fax number. The user always sees the rendered pages, the recipient and the price, and approves the charge, before anything is sent. Failed faxes are refunded automatically.

## Connection

| Field | Value |
| --- | --- |
| Product | Paper Owl Fax |
| Developer | Vectis Studio LLC |
| Website | https://sendpaperowl.com |
| MCP endpoint | https://api.sendpaperowl.com/fax/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/fax/v1 (OpenAPI: https://api.sendpaperowl.com/fax/openapi.json) |
| Docs | https://api.sendpaperowl.com/fax/docs |
| llms.txt | https://api.sendpaperowl.com/fax/llms.txt |
| Health | https://api.sendpaperowl.com/healthz |
| Terms | https://sendpaperowl.com/legal/terms |
| Privacy | https://sendpaperowl.com/legal/privacy |
| Support | support@sendpaperowl.com (https://sendpaperowl.com/#support) |
| Rate limits | 120 requests per minute per IP; 20 drafts per hour per IP; 10 drafts per hour and 5 sends per day per recipient number |

## Transport rules

- Send JSON-RPC with `POST` and `Content-Type: application/json`. `Accept: application/json` alone is fine.
- A `GET` returns 405. That means the server is up.
- No session header is issued or needed. Every request stands alone.

## Flow

1. Ask the user for the sender name if you do not already have it: their own name or their business name, as the recipient should see it.
2. Call `create_fax_draft` with `from_name`, `to` and exactly one of `text`, `pdf_base64` or `pdf_url`.
3. Tell the user the sender name, the recipient, the page count and the price, and offer `preview_url` so they can see every page. Do this before asking for payment.
4. Then one of:
   - **In-chat payment (Muse):** ask the user to approve the exact price and to confirm the fax is not an unsolicited advertisement. Call `send_fax` with the `draft_id`, the granted Stripe shared payment token (`spt_...`) as `payment_token`, and `attest_not_advertisement: true`.
   - **No in-chat payment:** give the user `review_url`. They check the pages, tick the box and pay with Stripe Checkout. The fax sends when payment clears.
5. Call `get_fax_status` about once a minute until `delivered`, `refunded`, `cancelled` or `expired`. Relay `next_step` to the user.

## Tools

| Tool | Use it when | Key arguments |
| --- | --- | --- |
| `create_fax_draft` | The user wants to fax something. Always first. | from_name, to, and one of text, pdf_base64, pdf_url; optional cover_page |
| `send_fax` | The user approved the exact price in chat and confirmed it is not an ad. | draft_id, payment_token, attest_not_advertisement: true |
| `get_fax_status` | After paying, to follow delivery. | draft_id |
| `cancel_fax_draft` | The user changed their mind before paying. | draft_id |

`send_fax` is the only tool that moves money. It charges exactly the quoted price, never more, even if the payment approval allows more. Repeating it for the same draft never charges or sends twice.

## Sender header

Every page carries one line in its top margin: `From: {from_name} via Paper Owl Fax`, the sending fax number, the date and time sent (America/Chicago), and the page number. Federal law (47 U.S.C. 227(d)) requires a fax to identify its sender, so `from_name` is required and must be the real sender. The preview shows the header; its date and time are set when the fax is sent.

## Pricing and limits

- $1.99 covers up to 5 pages, plus $0.25 for each page after that, up to 50 pages. Example: 8 pages cost $2.74.
- A cover page counts as a page.
- Documents: 10 MB maximum. `pdf_url` must be public https.
- US (50 states and DC) and Canada only. No 900 or 976 numbers, no N11 codes, no Caribbean or US territory numbers.
- Drafts expire after 24 hours unpaid.

## Status values

`draft` (unpaid), `paid`, `sending`, `delivered`, `failed` (refund in progress), `refunded`, `cancelled`, `expired`.

## Will not do

- Send to more than one number per draft, or send bulk faxes.
- Send unsolicited advertising (Junk Fax Prevention Act).
- Send medical records or other protected health information.
- Charge the user without their approval, or charge more than the quote.

## Errors

Tool errors come back with `isError: true` and a JSON body `{"error": {"code", "message"}}`. The message is safe to show the user. Common codes: `INVALID_NUMBER`, `UNSUPPORTED_DESTINATION`, `TOO_MANY_PAGES`, `URL_NOT_ALLOWED`, `DRAFT_EXPIRED`, `PAYMENT_DECLINED`, `PAYMENT_TOKEN_INVALID`, `PAYMENT_IN_PROGRESS`, `RATE_LIMITED`.

## Examples

```bash
curl -sS https://api.sendpaperowl.com/fax/mcp -H 'content-type: application/json' -H 'accept: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```

```bash
curl -sS https://api.sendpaperowl.com/fax/mcp -H 'content-type: application/json' -H 'accept: application/json' -H 'mcp-protocol-version: 2025-06-18' -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_fax_draft","arguments":{"from_name":"Ada Lovelace","to":"+15015550134","text":"Hello from Paper Owl Fax"}}}'
```