PostAgent

PostAgent lets an AI agent send real, physical mail.

CommunityOnlineNo sign-inGlobalFreeCan modify data

What it can do

Create Letter: Upload and normalize a FINISHED, ready-to-mail document to PDF. Choose this when the content is final and IDENTICAL for every recipient — including when you mail the same letter to many
Create Template: Upload a REUSABLE template containing `{{field}}` placeholders (e.g. `Dear {{name}},` or `Balance due: {{amount}}`). Choose this ONLY when the content must vary per recipient (mail me
Create Mail Quote: Verifies the recipient and sender US addresses and locks a 15-minute USDC price for a documentId. Does not charge or mail anything. Returns a `paymentUrl` (a per-quote x402-payable

What data it sees

Do you need an account

No: the server works without sign-in

PostAgent lets an AI agent send real, physical mail. Upload a document, lock a price quote, pay per send, and PostAgent prints it and ships it via USPS.

Built for autonomous agents: pay per call in USDC on Base via the x402 protocol or credit cards, no signup, no human-issued API key, no billing account.

What it does

Letters — PDF, HTML, Markdown, text, DOCX, or image; black & white or color. Optional certified, certified-with-return-receipt, or registered mail for proof of delivery.
Postcards — 4×6, 6×9, 6×11, full color from front/back artwork (4×6 can ship internationally).
Address verification — standalone US/international deliverability check (~2¢ per call).
Mail merge — personalize one template across many recipients with {{fields}}.
Bulk campaigns — one creative to up to 500 recipients (KYC-gated).

Quotes are free and verify both sender and recipient addresses; the server always quotes first and only mails after explicit confirmation. Sends spend real money and are irreversible once submitted. US recipients · pay-as-you-go · no subscription.

Server tool list (13)

Raw names from tools/list. Only developers need these.

create_letter	Upload and normalize a FINISHED, ready-to-mail document to PDF. Choose this when the content is final and IDENTICAL for every recipient — including when you mail the same letter to many people (just quote/pay once per recipient with the same documentId). The exact bytes you give are what gets printed. Use create_template instead only when the content must vary per recipient via {{fields}}. Returns a documentId, the stored page count, byte size, and source format. Free; no payment required. Provide the document EXACTLY ONE way: `content` (inline text, for html/markdown/text), `contentBase64` (base64-encoded binary, for pdf/docx/image), or `url` (a publicly reachable URL the server fetches). Supplying none, or more than one, is an error. Maximum upload size is 31457280 bytes (~30 MB); output page size is US Letter. Any `{{...}}` text is printed LITERALLY here — it is NOT treated as a merge field. If you want personalized mail merge across recipients, use `create_template` instead. Reserved address zone: a recipient address block is printed over the top ~3 inches of page 1, so the server reserves that space for you automatically. For text/html/markdown/docx, page-1 content is pushed below the block (content may therefore flow onto an additional page); for pdf and image inputs, a blank first page is prepended. As a result the returned page count — and the per-page price in the resulting quote — can be one more than your source document (e.g. a single-page PDF is stored as 2 pages). You do NOT need to leave the top of your document blank yourself. See the postagent://formats resource for per-format details.
create_template	Upload a REUSABLE template containing `{{field}}` placeholders (e.g. `Dear {{name}},` or `Balance due: {{amount}}`). Choose this ONLY when the content must vary per recipient (mail merge) — recipient count is irrelevant, so a single personalized letter belongs here too. If the content is identical for everyone, use create_letter instead (this tool rejects input with no `{{fields}}`). Returns a documentId with `kind: "html_template"`, a `mergeFields` list of the detected field names, and an `estimatedPageCount`. Free; no payment required. Template source must be TEXT-BASED (html, markdown, or text) and must contain at least one `{{field}}`, or the upload is rejected — for a finished document with no merge fields, use `create_letter`. Provide the template EXACTLY ONE way: `content` (inline text), `contentBase64` (base64-encoded text), or `url` (a publicly reachable URL the server fetches). Supplying none, or more than one, is an error. Maximum upload size is 31457280 bytes (~30 MB); output page size is US Letter. Reuse one template documentId across recipients: call create_mail_quote ONCE PER RECIPIENT, supplying that recipient's values via `mergeVariables` (every field in `mergeFields` must have a non-empty value). The server substitutes the values and renders that recipient's personalized PDF at quote time, so `estimatedPageCount` is only a baseline — the binding page count and price are set per quote from the actual rendered output. Reserved address zone: a recipient address block is printed over the top ~3 inches of page 1, so the server reserves that space automatically (page-1 content is pushed below the block and may flow onto an additional page). You do NOT need to leave the top blank yourself. See the postagent://formats resource for details.
create_mail_quote	Verifies the recipient and sender US addresses and locks a 15-minute USDC price for a documentId. Does not charge or mail anything. Returns a `paymentUrl` (a per-quote x402-payable URL); the preferred way to actually mail the letter is for the agent's wallet to perform an in-band x402 payment against that URL (e.g. `npx awal@latest x402 pay <paymentUrl>`). The MCP `submit_paid_mail_job` tool is a fallback for clients that can emit a standalone signature header. In all cases, show the recipient, sender, options, and price to the user and get explicit confirmation before paying.
create_card_checkout	Creates a Stripe-hosted Checkout page for a locked quote and returns a `checkoutUrl` plus a `statusUrl`. Use this as the LAST-RESORT payment rail, when the payer is a human paying by credit card (the agent cannot complete card entry itself). Hand the `checkoutUrl` to the user to open in a browser and pay; payment is asynchronous — once they finish, the letter is created automatically by Stripe's webhook. To track it without a job id, GET the returned `statusUrl` (`/v1/quotes/:quoteId/job`): it returns `found:false` with status `pending`/`processing` until the webhook creates the job, then the full job (id, status, tracking). Prefer x402 (or MPP, if available) for autonomous agent payment. Returns an error if Stripe Checkout is not enabled on the server. No charge occurs until the human completes the hosted page.
pay_mail_with_shared_payment_token	Autonomous, no-browser FIAT payment for a locked quote using a Stripe Shared Payment Token (SPT / Machine Payments Protocol). Use this when the agent can mint an SPT on the buyer's behalf and wants to pay by card/wallet without a human in a browser (prefer x402 first if the agent has a USDC-on-Base wallet; this is the autonomous fiat alternative). CHARGES MONEY AND IS IRREVERSIBLE: the server authorizes the SPT, prints the letter, then captures — a job comes back inline (no polling needed). Only call after the user has explicitly confirmed the recipient, sender, content, and price from create_mail_quote. Minting the token (the agent's responsibility, NOT this server): the SPT must be scoped to THIS seller's Stripe profile and to at least the quote amount. The quote's `paymentOptions` entry for `mpp` carries the `stripeProfileId`, `currency`, `maxAmountCents`, and `expiresAt` you need. Mint it with the buyer's payment method via the Stripe `@stripe/link-cli` (`spend-request create … --network-id <stripeProfileId> --credential-type shared_payment_token`) or the SharedPaymentIssuedToken API, then pass the resulting `spt_…` here. SPTs are US-only and cards carry a 0.50 USD minimum. Returns an error if MPP is not enabled/configured on the server.
prepare_mail_payment	Returns the x402 PAYMENT-REQUIRED challenge for a locked quote so an x402-capable wallet client can sign it. No payment is taken at this step. Probes the canonical per-quote pay URL (`/v1/quotes/:quoteId/pay`). The preferred way to actually pay is for the wallet to perform the standard x402 in-band handshake against `paymentUrl`; this tool is for inspection or for the detached-signature flow via `submit_paid_mail_job`.
submit_paid_mail_job	Detached-signature fallback for x402 wallets that can emit a standalone PAYMENT-SIGNATURE header. THE PRIMARY/RECOMMENDED PATH is for the agent's wallet to pay the quote's `paymentUrl` in-band (e.g. `npx awal@latest x402 pay <paymentUrl>`); use this tool only if your wallet client cannot do that. Charges the agent in USDC on Base mainnet and creates a physical letter for printing and mailing. THIS IS IRREVERSIBLE. Only call after the user has explicitly confirmed the recipient, sender, content, and price returned by create_mail_quote, and after obtaining the signed x402 payment header (see prepare_mail_payment).
get_mail_job_status	Returns normalized status, provider letter id, and tracking events for a previously created job.
create_postcard_art	Upload ONE side of a postcard (front or back) as single-page PDF, PNG, or JPEG artwork. The file is stored VERBATIM — no page-size normalization and no reserved address zone — so you are responsible for the correct trim size plus bleed: 4x6 cards need 4.25"x6.25" artwork, 6x9 needs 6.25"x9.25", 6x11 needs 6.25"x11.25" (0.125" bleed on each edge). Lob prints the recipient address block over part of the BACK, so keep that area clear of critical content. Returns a documentId with kind "postcard_art". Upload front and back separately, then quote with create_postcard_quote. Free; no payment required. Provide the artwork EXACTLY ONE way: `contentBase64` (base64-encoded pdf/png/jpeg) or `url` (publicly reachable). Text-based formats are rejected — postcards are artwork, not documents.
create_postcard_quote	Verifies the recipient and sender addresses and locks a 15-minute USDC price for mailing a postcard built from two postcard_art documents (front + back, uploaded via create_postcard_art). Sizes: 4x6 (default), 6x9, 6x11 — postcards always print in full color. US recipients use the strict US address shape; INTERNATIONAL recipients are supported on 4x6 only (set `to.country` to the 2-letter ISO code; the sender must still be a US address). Payment works exactly like letters: pay the returned `paymentUrl` via x402, or use the MPP/checkout fallbacks. Show the recipient, sender, size, and price to the user and get explicit confirmation before paying.
verify_address	Standalone paid address verification — no mail is sent. Checks whether an address is deliverable and returns the standardized form (US: CASS with ZIP+4; international: per-country matching). Costs a small flat USDC fee per call via x402 (a fraction of a cent vs. mailing). Two-step flow, like the mail rails: call WITHOUT `paymentSignature` to get the 402 challenge and `paymentUrl` (preferred: have the agent's x402 wallet pay `paymentUrl` in-band with the address as the JSON POST body `{"address":{...}}`); or sign the challenge and call again WITH `paymentSignature` to verify and get the result in one round trip. US addresses need line1 + (city+state or zip). International addresses need line1 + country. Note: when mailing through PostAgent you do NOT need this tool — create_mail_quote already verifies sender and recipient for free as part of the quote.
create_campaign_quote	Quote ONE bulk send to MANY recipients (up to 500): a single template or static document, fulfilled through the mail provider's campaign pipeline. Price = per-letter unit price x recipient count, locked for 15 minutes. Payment is x402 ONLY. IMPORTANT — KYC WALL: campaigns require the paying wallet to be identity-verified with PostAgent. KYC onboarding is NOT YET AVAILABLE, so this tool currently returns `kyc_required` (403) for every wallet. Do not retry; mail recipients individually with create_mail_quote instead, or wait for KYC onboarding to launch. Usage once KYC exists: upload a template with create_template (using {{fields}}) or a finished letter with create_letter, then call this with `recipients` (each `to` a US address, plus per-recipient `mergeVariables` for templates) and the `payerWallet` that will pay the quote. The provider validates every recipient address after payment; failed recipients are excluded and their share refunded (processed manually). Track via get_campaign_status.
get_campaign_status	Returns a campaign's validation/sending progress: status (validating \| sent \| partial \| failed), recipient counts (total / validated / failed), and a failures report URL when some recipients could not be validated. Polling this endpoint also advances the campaign (it releases the campaign for mailing once the provider finishes validating the audience). Find the campaign id on the quote's job status (GET jobStatusUrl) after payment.