Paper Owl Mail docs

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, from an AI assistant. The user sees every page, both addresses and the price, and approves the charge before anything is printed.

Connect

• MCP endpoint: https://api.sendpaperowl.com/mail/mcp (stateless Streamable HTTP, POST only, JSON responses)
• REST API: https://api.sendpaperowl.com/mail/v1, OpenAPI 3.1
• Agent brief: muse.md; summary: llms.txt

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.

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.

Tools

• create_mail_draft: Prepare one printed letter to one US address (the 50 states and DC) and get its price. This creates an unpaid draft only: nothing is printed and nothing is charged. Provide "from" (the user's own real name and a US mailing address where they receive mail; printed as the return address; ask the user, never guess), "to" (the recipient's name and address), "service" (first_class, certified or certified_return_receipt), and exactly one letter source: "text" (plain text or simple Markdown), "pdf_base64", or "pdf_url" (public https, 10 MB max). Both addresses are checked against USPS records; an undeliverable address is refused, and a missing apartment or suite number must be added. Letters are black and white, single-sided, at most 5 pages; a Certified Mail letter from a PDF at most 4 pages. Returns a draft_id, both addresses as they will print, any USPS changes (address_changes), the pages, the price, payment_terms, a preview_url, a review_url, and when the draft expires (24 hours). Read payment_terms to the user word for word, show both addresses and any changes, the service, pages and price, and offer the preview link before asking for payment. Then either ask the user to approve the charge in chat and call send_mail, or, if your client cannot take payments, give the user the review_url. Reviewers: a recipient named "Paper Owl Mail Test Desk", at any address, is the test path: charged, never printed, refunded in full automatically. Will not: send to more than one address, mail outside the 50 states and DC, or send advertising, bulk mail, bill-like solicitations, debt collection or political campaign mail. 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.
• send_mail: CHARGES THE USER MONEY. Charges exactly the price quoted by create_mail_draft, then holds the letter for 15 minutes, during which the user can cancel it with cancel_mail for a full refund; after that it goes to print. Only call this after the user has seen both addresses, the service, the pages and the price, has approved that exact charge in chat, and has confirmed 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. Pass the draft_id, the Stripe shared payment token (spt_...) granted by that approval, and attest_sender_and_content: true. Never invent or reuse a token. The charge is never more than the quote. If the charge fails, nothing is printed and the draft stays unpaid so the user can try again. Safe to retry: calling it again for the same draft never charges twice. Set dry_run: true to check the draft and the approval without charging. If your client cannot take payments in chat, do not call this; give the user the review_url instead. 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.
• get_mail_status: Look up a letter by draft_id. Read only; charges nothing. Returns the status (draft, paid, held, submitted, mailed, delivered, returned, failed, refunded, cancelled or expired), both addresses, the service, pages, price, when the free-cancel hold ends, the estimated print date, the USPS tracking number for certified letters, the refund status, and a next_step sentence you can relay to the user. During the hold, check again after it ends. Once the letter is at the printer or with USPS, check about once a day.
• cancel_mail: Cancel a letter by draft_id. Before payment: cancels the draft, nothing is charged. After payment and within the 15-minute hold: cancels the letter and refunds the full price. After the hold the letter has gone to print and cannot be cancelled; the call says so. Calling it again on a cancelled letter is harmless. Set dry_run: true to check whether it can still be cancelled without cancelling it.

Testing

A letter to the recipient name Paper Owl Mail Test Desk, at any US address, runs the normal paid flow in test mode: it is never printed, and the charge is refunded in full automatically. 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.

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.

Terms and privacy. Support: support@sendpaperowl.com.