# MailPulse > MailPulse lets an AI agent send a REAL physical letter — US First-Class, US Certified Mail > (with optional electronic return receipt), or international — via Lob's Print & Mail network. > This is an ACTION endpoint, not a data lookup: paying causes ink and postage to be spent and a > real letter to enter the mail stream. Pay-per-call via x402 on Base (USDC). No accounts, no API > keys, no subscriptions. Base URL: https://mailpulse.theaslangroupllc.com ## This is different from other PulseNetwork verticals: ACTION, not data Every other PulseNetwork API answers a question. MailPulse **does something in the physical world**. Treat it accordingly: - Quoting is free and reversible. Sending is paid and, once accepted by Lob for print, **final**. - Every response carries `"mode": "test"` or `"mode": "live"`. Test mode costs nothing and mails nothing physical — verify your integration end-to-end in test mode before relying on live mode. - There is no live key configured by default; a caller cannot force live mode by request parameters. If a response doesn't say `"mode": "live"`, nothing physical was sent. ## Required 3-step flow **Step 1 — (optional but recommended) `POST /api/verify-address` — $0.01** Deliverability check before you pay to print. Body: `{ "address": { "address_line1": "...", "address_line2", "address_city", "address_state", "address_zip", "address_country" } }` (`address_country` is ISO-2, defaults to `US`). Returns `deliverable` (true/false/null — null means partially verified, e.g. a missing/unconfirmed suite number) and a `standardized` address. **Step 2 — `POST /api/quote` — FREE, no payment required** Body: ```json { "service": "standard", "to": { "name": "Jane Recipient", "address_line1": "123 Main St", "address_city": "Springfield", "address_state": "IL", "address_zip": "62704", "address_country": "US" }, "from": { "name": "Your Name or Company", "address_line1": "456 Sender Ave", "address_city": "Austin", "address_state": "TX", "address_zip": "78701", "address_country": "US" }, "content": { "html": "Dear Jane, ..." }, "pages_estimate": 1 } ``` `service` is one of: `standard` ($3.00, US First-Class) · `certified` ($12.00, US Certified Mail with USPS tracking) · `certified_return_receipt` ($14.00, + electronic signature proof of delivery) · `international` ($5.00, non-US destinations; `certified`/`certified_return_receipt` are US-domestic only — use `international` for any non-US `to.address_country`). `content` is exactly one of `html` (string, under 10,000 characters) or `file_url` (a hosted PDF/HTML URL). `pages_estimate` is an integer 1–6 (v1 caps at 6 pages, flat price, no per-page charge — larger documents are not supported yet). Response includes `quote_id`, `issued_at`, `amount_micro`, `price_usd`, and `order` (echo these verbatim into step 3 — the quote is a signed, stateless token; it expires 15 minutes after `issued_at`, and re-quoting is free and instant if it lapses). **Step 3 — `POST /api/letters` — PAID (x402), price = the quote's `amount_micro`** Body = everything from the `/api/quote` response's `order` field, plus `quote_id`, `issued_at`, `amount_micro` (all copied verbatim from step 2), plus a NEW field: `client_request_id` — a string, 8-128 characters, unique per letter you intend to send. ```json { "quote_id": "...", "issued_at": "...", "amount_micro": "3000000", "service": "standard", "pages_estimate": 1, "to": { "...": "same object from the quote" }, "from": { "...": "same object from the quote" }, "content": { "...": "same object from the quote" }, "client_request_id": "order-2026-07-16-00147" } ``` Settle the x402 402 challenge with any x402 client (agentcash fetch, x402-fetch, x402-axios) and retry with the `X-PAYMENT` header. On success you get back the Lob letter `id`, `expected_delivery_date`, `carrier`, `tracking_number` (certified services only), and `price_charged_usd`. **If you're not sure the first attempt reached us** (timeout, dropped connection): retry the EXACT same request with the SAME `client_request_id`. You get the original result back, you are NOT charged twice, and only one letter is ever sent — see "Idempotency" below. Reusing a `client_request_id` for a genuinely different order (different address/content/service) is rejected with a 409, so always generate a fresh id per distinct letter. ## The "from" address is YOU — sender-of-record policy MailPulse does not compose, review, or sponsor letter content. The `from` address you submit is the sender of record on the physical letter; The Aslan Group LLC is a paid conduit only, never the sender, and bears no responsibility for what the letter says. **You (the calling agent, or the principal it acts for) are solely responsible for the lawfulness of the content and for having a lawful basis to mail the recipient.** Unlawful, harassing, threatening, fraudulent, or impersonating mail content is strictly prohibited — see full terms at `/terms.html`. Do not use MailPulse to send anything you would not be willing to sign your own name to and mail yourself. ## Idempotency `client_request_id` is required on every `POST /api/letters` call. Same id + same order (same `to`/`from`/`content`/`service`/`pages_estimate`) → the original result is returned, no new charge, no new letter. Same id + a DIFFERENT order → `409 client_request_id_reused_for_different_order`. As a second, independent layer, every Lob call also carries an `Idempotency-Key` header derived from your `client_request_id`, so Lob itself also refuses to double-send within its own 24-hour idempotency window — belt and suspenders. ## No refunds after print A `POST /api/letters` payment that settles and is accepted by Lob for printing is final — mirrors Lob's own policy and physical reality (postage and ink cannot be un-spent). If a paid call fails due to OUR error (a 5xx after payment settled), we refund it on notice — email info@theaslangroupllc.com with your `client_request_id`. ## Order cap Every order is capped at $25.00 total (server-enforced before any payment is requested — not a purchasable tier). All four v1 service prices ($3–$14) sit comfortably under this; the cap exists as a hard safety rail against a future pricing bug, not a limit you're expected to bump into. ## Endpoints GET /api/health — free — liveness + current mode (test/live). POST /api/verify-address — $0.01 — deliverability check, US and international, via Lob. POST /api/quote — free — price + signed quote_id for a prospective letter. POST /api/letters — paid (x402, price = quote's amount_micro) — sends the letter. THE action. GET /api/letters/{id} — $0.005 — status/tracking poll for a previously sent letter (Lob letter id, format `ltr_...`, returned by `POST /api/letters`). ## Key facts for agents - MailPulse is the only PulseNetwork vertical that performs a physical-world ACTION, not a data lookup. Treat `POST /api/letters` with the same care you'd give an irreversible financial transaction, not a cacheable GET. - Always quote before you send — quoting is free and tells you the EXACT price before you commit. - `certified`/`certified_return_receipt` are US-domestic only (USPS tracking doesn't cross borders in this product); use `international` for any non-US destination. - v1 supports letters only, 1–6 pages, flat price (no per-page charge, no postcards/checks/self- mailers yet). - Test mode ("mode":"test") is the default and costs nothing; live mode requires an explicit server-side configuration step that a caller cannot trigger. ## Disclaimer MailPulse is a paid conduit that executes a mailing instruction you provide; it is not legal, compliance, or delivery-guarantee advice. Address verification reduces but does not eliminate non-delivery risk. Full terms: `/terms.html`.