# Mailr > Mailr is a direct mail API. Send personalized postcards, flats and folded mailers from your own code: one HTTPS request prints the piece, applies postage, hands it to USPS and tracks every scan. Full reference: https://mailr.dev/docs ## Basics - Base URL: https://api.mailr.dev/v1 - Auth: `Authorization: Bearer `. Keys are created in the dashboard at https://mailr.dev/app and shown once. - Test keys (mlr_test_…) are free and never print; their pieces move through every status in about 8 minutes. An address whose line1 or line2 contains "undeliverable" fails after 30 seconds. Live keys (mlr_live_…) print, mail and spend credits. - Bodies are JSON. Responses are JSON with an `id`, a `status` and `events`. ## Endpoints - POST /v1/postcards — create a postcard. Fields: size ("4x6" | "5.5x8.5" | "6x9" | "6x11"), to (name, line1, line2?, city, state, zip), from (your return address, same shape, required), template (template id) or front + back (HTML string with {{merge}} tags, or a PDF URL), merge (object of merge-field values), description (optional). - POST /v1/flats — create a flat mailer. Same fields; size "8.5x11" | "8.5x14" (single sheet) or "11x17" (folded to 8.5x11). Flats mail without an envelope. - GET /v1/postcards/{id} and GET /v1/flats/{id} — the piece with its current status and events. - GET /v1/postcards?limit=25 and GET /v1/flats?limit=25 — newest first, up to 100, for the calling key's mode. - Credits per live piece: 4x6 postcard 1; 5.5x8.5, 6x9 and 6x11 postcards 2; flats 3. - Errors: {"error": {"code", "message", "field"?}}. 400 invalid_json, 401 unauthorized, 402 insufficient_credits, 404 not_found, 422 invalid_request. - Statuses: queued → rendered (proof ready) → printed → mailed → in_transit → processed_for_delivery, or failed. ## Tracking Retrieve a piece to see its status and events (event types look like postcard.mailed). Webhooks are not available yet. ## Templates (ready for coding agents) - tmpl_thank_you (postcard, 6x9): First-order thank you. Trigger: Shopify orders/fulfilled, when the customer’s first order is fulfilled. Merge fields: first_name, promo_code. Spec: https://mailr.dev/templates/tmpl_thank_you/template.json - tmpl_winback (postcard, 6x11): Win-back. Trigger: Your database nightly job, when a customer’s last order is 60+ days old. Merge fields: first_name, promo_code, last_product. Spec: https://mailr.dev/templates/tmpl_winback/template.json - tmpl_welcome (flat, 8.5x11): Welcome letter. Trigger: Your app user.created, when a new account confirms its email. Merge fields: first_name, company, founder_name. Spec: https://mailr.dev/templates/tmpl_welcome/template.json - tmpl_payment_failed (flat, 8.5x11): Failed payment. Trigger: Stripe invoice.payment_failed, when the third retry fails. Merge fields: first_name, plan, update_url. Spec: https://mailr.dev/templates/tmpl_payment_failed/template.json - tmpl_abandoned_cart (postcard, 6x9): Abandoned cart. Trigger: Shopify checkouts/create, when a checkout is still open after 48 hours. Merge fields: first_name, product_name, cart_url. Spec: https://mailr.dev/templates/tmpl_abandoned_cart/template.json - tmpl_review_request (postcard, 4x6): Review request. Trigger: Shopify orders/fulfilled, when 21 days after delivery. Merge fields: first_name, product_name, review_url. Spec: https://mailr.dev/templates/tmpl_review_request/template.json Every template has three files at https://mailr.dev/templates//: - template.json: trim size, bleed, safe area, keep-clear zone (where Mailr prints the address, plus postage and barcode on postcards) and a max_length for each merge field. Read it first. - front.html and back.html: print-ready HTML at true size in inches, with {{merge}} tags, 0.125 in bleed on every side and a 0.125 in safe area. Postcards are landscape; flats are portrait 8.5x11. Print rules the files follow (USPS Domestic Mail Manual 201 and 202): - Postcard back: an ink-free box 4 x 2.375 in (3.2835 x 2.375 in on 4x6), 0.15 in from the right trim edge and 0.125 in from the bottom, holds the address, postage and Intelligent Mail barcode. Return address goes top left. - Postcard front: no address-like text in the bottom 2.375 in. - Flat back: a 4 x 2.375 in address panel at the top right, 0.25 in from the top and right trim edges. USPS wants a flat's whole address in the top half (DMM 202.2.2). On the front, keep promotional addresses out of the top half. - On First-Class Mail, cards up to 6 x 9 in pay the card price and a 6x11 card pays the letter price. On USPS Marketing Mail (200-piece minimum per mailing) every postcard pays the letter rate. What goes on a piece (template.json lists it per template under "content"): - Mailr prints: the recipient name and address from `to`, the return address from `from` (required), postage (the indicia for the mail class) and the Intelligent Mail barcode. They go in the address block on the back (bottom right on postcards, top right on flats). Never draw them in the design. - You can add, in your own style: logo, colors, fonts (TTF, WOFF, WOFF2 or Google Fonts), images (PNG or JPG at 300 DPI), QR codes (1 in or larger), your own business address, phone and website, and any {{merge}} tags. All asset URLs must be public https links. - Don't add: stamps, permit imprints or postage marks, postal-looking barcodes, the recipient's address anywhere else on a postcard, or sensitive personal data (account numbers, amounts, health or money details). Postcards and flats mail without an envelope. To customize a design, copy front.html and back.html into the codebase, edit them, keep the page size, bleed, safe area, keep-clear zone and merge tags, and send them as front and back. A copy-paste agent prompt for each template is at https://mailr.dev/templates ## Tips for agents - Read the API key from the MAILR_API_KEY environment variable; never hard-code it. - Store the returned id on your own record so the same person is not mailed twice for the same event. - Use the template's merge fields exactly as listed; missing values fail validation before anything prints. - Keep merge values under the max_length in template.json, and never put text or art in a keep-clear zone. ## Links - Home: https://mailr.dev - Docs: https://mailr.dev/docs - Templates: https://mailr.dev/templates - Dashboard: https://mailr.dev/app