MailSnail changelog

icon_url

— → https://mailsnail.dev/brand/mailsnail-icon-512.png

title

mailsnail → MailSnail

version

0.6.1 → 0.6.2

description

Send USPS letters, postcards & certified mail from any agent. No signup; pay-per-piece via Stripe. → Send USPS letters & certified mail from any agent. Hosted: sign in, no install.

remote_url

— → https://api.mailsnail.dev/mcp

transport

stdio → streamable-http

version

0.6.0 → 0.6.1

https://mailsnail.dev/llms.txt

− ## Tools — managed mode (9)− - get_letter: Delivery status for a letter. Free.− Not available in managed mode: list_letters, cancel_letter. Those exist only in self-hosted mode, where the provider account belongs to the operator.− - cancel_letter: Cancel before production (short, provider-specific window).+ ## Tools — managed mode (10)+ - get_letter: Status of a sent letter, including the USPS tracking number and a usps.com link for certified mail, and a link to the signature PDF for an electronic return receipt. Free. Args: receipt_token (returned by send_letter).+ - cancel_letter: Cancel a letter before printing starts (usually possible for about a day after sending) and refund its full price to the balance. Only for letters paid from the signed-in account's balance. Args: receipt_token.+ Not available in managed mode: list_letters. It exists only in self-hosted mode, where the provider account belongs to the operator.+ - cancel_letter works there too, against your own provider account (short, provider-specific window).

https://mailsnail.dev/llms.txt

− > The way AI agents send physical mail. Mailsnail is an MCP server that lets Claude, Cursor, Codex, and any agent send real letters and postcards via USPS. Add the remote server, sign in from your client, and mail draws against a prepaid balance — or self-host it against your own Click2Mail or Lob account.− - verify_address: US address validation. FREE, never charges, never mails. Run on user-provided addresses before sending.− - preview_letter: Proof PDF + exact price WITHOUT charging or mailing. Returns proof_url, draft_id, verified address, price. RECOMMENDED FIRST STEP: preview, show the user the proof_url and price, get explicit confirmation, then send_letter with the draft_id.− - send_letter: Mail a letter to a US address, charged to the signed-in user's balance. Args: to (address), from (address), and EITHER body_text (plain text, we render the PDF) OR file_url (URL to your own PDF). Optional: draft_id, color, double_sided, extra_service ("certified", "certified_return_receipt", "certified_return_receipt_electronic"), description.− - send_postcard: Mail a postcard. Provide a public URL to a PDF with front and back combined.− - get_balance: Balance, saved payment method, auto-reload settings. FREE.− - add_payment_method: Returns setup_url to add a first card (adds card AND funds balance in one step), or billing_portal_url to change an existing one. Safe to show the user.− - top_up: Add funds from the card on file. CHARGES IMMEDIATELY — only call when the user explicitly asks. Routine sends top up automatically.− - get_letter: Delivery status for a letter. FREE.− - get_postcard: Delivery status for a postcard. FREE.− All of the above except add_payment_method (no balance to fund), plus:− 3. Call send_letter. If there is no card yet the tool returns `{ "error": "payment_setup_required", "setup_url": "https://checkout.stripe.com/..." }`. Show that URL to the user — it adds a card and funds the balance in one step.− 4. Retry the identical call. The letter mails.− Mail draws against a prepaid balance rather than charging a card per piece, because a fixed per-charge processing fee would be a fifth of the price of a $1.50 letter. Auto-reload tops the balance up from the saved card so an agent does not stall mid-task; the user sets the amounts and can switch it off in the Stripe billing portal.− - Retry the identical request with "payment_token": "spt_..." to pay for that piece.− - First-class letter:                 $1.50− - Certified letter:                   $9.75− - Certified + return receipt (green card): $17.00− - Certified + electronic return receipt:   $15.00− - Postcard (4x6):                     $1.00+ > The way AI agents send physical mail. Mailsnail is an MCP server that lets Claude, Cursor, Codex, and any agent send real letters and certified mail via USPS. Add the remote server, sign in from your client, and mail draws against a prepaid balance — or self-host it against your own Click2Mail or Lob account.+ - verify_address: US address validation. Free: never charges, never mails. Useful on user-provided addresses before sending.+ - preview_letter: Proof PDF + exact price without charging or mailing. Returns proof_url, draft_id, verified address, and both prices: amount_cents (from the prepaid balance) and pay_per_letter_cents (paying for just this letter by card, which includes the card fee). The usual flow is preview, let the user review the proof and price, then send_letter with the draft_id.+ - send_letter: Mail a letter to a US address, charged to the signed-in user's balance. If the balance can't cover it, the result carries two Stripe links: setup_url (add funds) and pay_per_letter_url (pay for just this letter by card). Paid and irreversible (annotated destructiveHint). Args: to (address), from (address), and EITHER body_text (plain text, we render the PDF) OR file_url (URL to your own PDF). Optional: draft_id, color, double_sided, extra_service ("certified", "certified_return_re+ - get_balance: Balance, saved payment method, auto-reload settings. Free.+ - add_payment_method: Always returns setup_url, a Stripe page to add funds. By default it is a one-time payment for amount_cents (default $25) and the card is not saved. With auto_reload: true the same page also saves the card and shows the auto-reload terms the user agrees to by paying. If a card is on file it also returns billing_portal_url (update the card, view receipts). Charges nothing by itself.+ - turn_off_auto_reload: Turn off automatic charges to the user's saved card. The card stays on file. Free: charges nothing. Team accounts: organization admins only.+ - get_letter: Delivery status for a letter. Free.+ - send_postcard: Temporarily unavailable.+ - get_postcard: Temporarily unavailable.+ There is no managed-mode tool that charges a card on demand: payment happens on Stripe's pages, via setup_url (add funds) or pay_per_letter_url (pay for one letter). Auto-reload is opt-in; sends reload the balance automatically only for a user who chose it.+ All of the above except add_payment_method and turn_off_auto_reload, plus:+ 3. Call send_letter. If the balance can't cover it and no card is saved for auto-reload, the tool returns `{ "error": "payment_setup_required", "setup_url": "https://checkout.stripe.com/...", "pay_per_letter_url": "https://checkout.stripe.com/...", "pay_per_letter_cents": 151 }`. Show both links to the user. pay_per_letter_url is a one-time payment of pay_per_letter_cents for just this letter. setup_url is a one-time payment that adds funds to the balance (default $25). Neither saves the card or+ 4. Retry the identical call after either payment. The letter mails.+ There are two prices, both at our cost. Paying for one letter by card carries Stripe's whole processing fee (2.9% + 30¢), so it costs a little more. A prepaid balance spreads that fee over many letters, so letters cost less from it. preview_letter returns both prices.+ Auto-reload is opt-in. It only turns on if the assistant requests the funding link with auto_reload: true (add_payment_method). Stripe's page then saves the card and shows the terms, and the user agrees by paying: Mailsnail charges the saved card the reload amount (default $25, between $10 and $500) whenever the balance falls below the threshold (default $10), never more than $500 in one charge. A declined reload turns auto-reload off. To turn it off: call turn_off_auto_reload, email hello@mails+ - amount is the single-letter card price, which includes Stripe's whole processing fee: 151 cents for a one-page first-class letter. It is higher than the prepaid-balance price (amount_cents in preview_letter; pay_per_letter_cents is the card price).+ - Retry the identical request with "payment_token": "spt_..." to pay that amount for that piece.+ Two ways to pay, both at our cost. Extra pages and color are priced at our cost too.+ - First-class letter:                      from $1.21 from a balance; from $1.51 for one letter by card+ - Certified letter:                        from $8.61 from a balance; from $8.83 for one letter by card+ - Certified + electronic return receipt:   from $11.64 from a balance; from $11.83 for one letter by card+ - Certified + green-card return receipt:   from $14.27 from a balance; from $14.42 for one letter by card+ Those are one-page, black-and-white prices. A single card payment carries Stripe's whole processing fee (2.9% + 30¢); a prepaid balance (default top-up $25) spreads that fee over many letters. preview_letter returns the exact price for a piece before anything is charged: amount_cents is the balance price and pay_per_letter_cents is the card price.