For AI agents

The integration surface for LetterAgent.

If you're a person who just wants to mail things, ignore everything below: you never touch any of this. Start at the homepage.

LetterAgent is API-first. The website is just the brochure: the product lives inside the conversation. The canonical integration is the MCP server:

MCP endpoint: https://api.getletteragent.com/mcp
REST base:    https://api.getletteragent.com/v1

Point any MCP-compatible assistant (Claude, ChatGPT, or your own agent) at the MCP URL: no signup, no API key. The service is account-free by design: every item is paid individually at creation through Stripe, so there is nothing to log into and no credential to provision.

Agents reading this site: start with llms.txt: the 60-second brief on how everything works.

The 15 tools

Tool	What it does
`quote_letter`	Price a letter from its content: verified page count, exact price. Always first.
`create_letter_job`	Create the mailing job from an approved quote. Returns the Stripe Checkout URL.
`get_job_status`	Payment, fulfilment, and delivery/tracking status for any job.
`cancel_letter`	Cancel a letter job while the fulfilment window is open.
`quote_check`	Price mailing a paper check: flat $5.00 USD / C$7.00 CAD + tax, any face amount.
`create_check_job`	Create the check-mailing job. Needs payee, pre-registered bank account ID, face amount.
`quote_fax`	Price a send-only fax: $1.40 USD first page + $0.40 USD each extra page.
`create_fax_job`	Create the fax job from an approved quote. Fax sends only after payment.
`quote_shipping_label`	Price a parcel shipping label: flat C$14.99 + tax, Canada only.
`create_shipping_label_job`	Create the label job from an approved quote. Label is bought after payment; returns tracking + PDF.
`get_proof_of_mailing`	Proof-of-mailing receipt for a fulfilled letter or check job.
`create_shipping_order`	Operator tool: create a parcel shipping order in the provider account.
`buy_shipping_label`	Operator tool: buy a label for an existing shipping order. Spends real money.
`track_shipment`	Look up a parcel by tracking number: carrier, service, current status.
`get_shipping_balance`	Read the prepaid shipping balance.

create_shipping_order and buy_shipping_label are operator tools that spend the provider balance directly, outside the customer pay flow: treat them as consequential.

Machine-readable specs

mcp-tools.json: all 15 MCP tool definitions (also live at the endpoint via tools/list).
SKILL.md: the step-by-step assistant playbook: quote first, confirm the price, then create the job with a fresh idempotency key.
openapi.yaml: full REST spec (OpenAPI 3.1).
api.html: human-readable API reference with examples.
llms.txt: the 60-second brief.

The flow (follow it exactly)

Quote first, with the actual content. POST /v1/quotes (letters), /v1/check-quotes, /v1/fax-quotes, or /v1/shipping-quotes: the backend renders/verifies and returns the exact price. Never an estimate.
State the exact price and get explicit approval before creating anything. A price the user did not approve is never charged.
Create the job with the quote_id and the SAME content the quote priced, plus a fresh UUID idempotency_key per action (reuse it on retry: the backend returns the original job, never a duplicate). Changed content fails with code: "quote_content_mismatch" and creates nothing.
Hand the user the checkout_url. One Stripe Checkout per item. Fulfilment starts only after payment succeeds.
Report back. Job reference, what happens next, the price. Check status any time with GET /v1/jobs/<id>; cancel while the fulfilment window is open.

Examples

curl -X POST https://api.getletteragent.com/v1/quotes \
  -H "Content-Type: application/json" \
  -d '{"country": "CA", "color": false, "text": "Dear landlord, please fix the tap."}'

# {"quote_id": "q_...", "pages": 1, "amount_cents": 615, "currency": "CAD", ...}

curl -X POST https://api.getletteragent.com/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{"quote_id": "q_...", "idempotency_key": "uuid-here",
       "letter": {"to": {...}, "from": {...}, "html": "..."}}'

# {"job_id": "job_...", "checkout_url": "https://checkout.stripe.com/...", ...}

Shipping label

curl -X POST https://api.getletteragent.com/v1/shipping-quotes \
  -H "Content-Type: application/json" \
  -d '{"ship_to": {"first_name": "Jane", "last_name": "Doe",
                   "address1": "123 King St W", "city": "Toronto",
                   "region": "ON", "postcode": "M5V 1K4",
                   "phone": "+14165551234"},
       "lines": [{"name": "Books", "quantity": 2}],
       "service": "Expedited Parcel"}'

# {"quote_id": "q_...", "amount_cents": 1499, "currency": "CAD",
#  "tax_cents": 195, "tax_label": "HST (13%)",
#  "total_cents": 1694, "total": "C$16.94", ...}

Shipping labels: flat C$14.99 + tax, Canadian destinations only, parcels up to 5 kg. Recipient phone is required (the carrier needs it). The quote binds the price to the exact shipment details.

Fax

curl -X POST https://api.getletteragent.com/v1/fax-quotes \
  -H "Content-Type: application/json" \
  -d '{"country": "US", "text": "Dear billing, please see the attached."}'

# {"quote_id": "q_...", "pages": 1, "amount_cents": 140,
#  "amount": "$1.40", "currency": "USD", ...}

Send-only faxes to US and Canadian numbers: $1.40 USD first page + $0.40 USD each additional page, USD only, 200-page cap. No inbound.

Rules

NEVER create a job or take payment without the user's explicit approval of the EXACT quoted price.
NEVER reuse an idempotency_key across different actions; ALWAYS reuse it when retrying the same action.
Letter and fax bodies are private: summarize, never repeat verbatim outside the task.
NEVER ask the user for card details: payment uses the Stripe Checkout link.
NEVER ask for, or accept, raw bank account/routing numbers in chat. Checks are drawn on pre-registered bank account IDs only.
Standard mail is untracked: never claim delivery without carrier evidence. Registered/certified mail carries tracking; hand the tracking number to the customer.
A fax is a money movement and a sent fax cannot be unsent: state the destination number and exact total, get explicit approval first.
In mock payment mode (payment_mode: "mock"), no real charge occurs and nothing is mailed or sent.

Home · API docs · Contact: hello@getletteragent.com · No cookies. No tracking.