Direct mail for growth teams, with an API underneath. Read the docs →
Docs

API reference

Send a postcard or a flat with one HTTPS request. Mailr prints it, adds postage, hands it to USPS and tracks every scan.

Base URLhttps://api.mailr.dev/v1AuthAuthorization: Bearer mlr_…FormatJSON

Quickstart

  1. Sign in and create a test key. Test mail is free and never printed.
  2. Set it as MAILR_API_KEY in your environment.
  3. Send your first postcard. It shows up in your dashboard right away.
curl
curl https://api.mailr.dev/v1/postcards \
  -H "Authorization: Bearer $MAILR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": "6x9",
    "template": "tmpl_thank_you",
    "to":   { "name": "Ada Park", "line1": "2140 Sample Ave", "city": "Phoenix", "state": "AZ", "zip": "85016" },
    "from": { "name": "Acme Outdoor", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004" },
    "merge": { "first_name": "Ada", "promo_code": "TRAIL15" }
  }'
Node.js
const res = await fetch("https://api.mailr.dev/v1/postcards", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    size: "6x9",
    template: "tmpl_thank_you",
    to: { name: "Ada Park", line1: "2140 Sample Ave", city: "Phoenix", state: "AZ", zip: "85016" },
    from: { name: "Acme Outdoor", line1: "1 Example Way", city: "Phoenix", state: "AZ", zip: "85004" },
    merge: { first_name: "Ada", promo_code: "TRAIL15" },
  }),
});
const postcard = await res.json(); // save postcard.id on your customer record

The response is the postcard, with an id to save and a status that moves as the piece is printed and mailed:

201 Created
{
  "id": "psc_1f9c2a7e4b10",
  "object": "postcard",
  "mode": "test",
  "status": "queued",
  "size": "6x9",
  "template": "tmpl_thank_you",
  "credits": 2,
  "to": { "name": "Ada Park", "line1": "2140 Sample Ave", "city": "Phoenix", "state": "AZ", "zip": "85016" },
  "from": { "name": "Acme Outdoor", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004" },
  "merge": { "first_name": "Ada", "promo_code": "TRAIL15" },
  "description": null,
  "events": [
    { "type": "postcard.queued", "status": "queued", "at": "2026-11-18T19:08:00.000Z", "note": "Request accepted" }
  ],
  "created_at": "2026-11-18T19:08:00.000Z",
  "url": "https://mailr.dev/app/mail/psc_1f9c2a7e4b10"
}

Authentication

Every request sends an API key in the Authorization header: Bearer mlr_test_… or Bearer mlr_live_…. Create and revoke keys in the dashboard. The full key is shown once, when you create it; Mailr keeps only a hash. Read it from an environment variable and never put it in client-side code.

Test and live

The key decides the mode. A test key makes free pieces that are never printed; they move through every status on their own so you can build and test the whole flow. A live key prints and mails for real and spends credits. Live keys unlock once your account has credits.

To test a failure, use an address whose line1 or line2 contains the word undeliverable. The test piece fails after 30 seconds.

Create a piece

POST/v1/postcards

POST/v1/flats

Both take the same body. Flats are single sheets (8.5×11 or 8.5×14) or 11×17 folded to 8.5×11, mailed without an envelope.

sizestringrequired
One of the sizes for that kind of piece.
toaddressrequired
The recipient. See addresses.
fromaddressrequired
Your return address. Mailr prints it in the address block.
templatestring
A template id such as tmpl_thank_you. The template’s kind and size must match the request.
front, backstring
Your own design instead of a template: HTML with {{merge}} tags (up to 500 KB each), or an https link to a PDF.
mergeobject
Values for the design’s {{tags}}. See merge fields.
descriptionstring
Your own note, up to 255 characters.

Send either template or front and back.

A flat with your own HTML
curl https://api.mailr.dev/v1/flats \
  -H "Authorization: Bearer $MAILR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": "8.5x11",
    "front": "<html>…your front.html with {{first_name}}…</html>",
    "back":  "<html>…your back.html…</html>",
    "to":   { "name": "Priya Shah", "line1": "88 Juniper Ave", "line2": "Unit 4", "city": "Portland", "state": "OR", "zip": "97205" },
    "from": { "name": "Northwind", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004" },
    "merge": { "first_name": "Priya" }
  }'

Addresses

US addresses only. Mailr prints the recipient address, your return address, postage and the USPS barcode itself, so they never go in your design.

namestringrequired
Up to 40 characters.
companystring
Up to 40 characters.
line1stringrequired
Street address, up to 64 characters.
line2string
Apartment, suite or unit, up to 64 characters.
citystringrequired
Up to 40 characters.
statestringrequired
Two-letter state code, like AZ.
zipstringrequired
5-digit ZIP or ZIP+4.

Designs

Templates are ready to send: pass the template id and its merge fields. Each template also has print-ready HTML files and a spec (template.json) with the trim size, bleed, safe area and the keep-clear zone where Mailr prints the address block.

To use your own design, start from a template’s front.html and back.html, change them, and send them as front and back. Keep the page size, the 0.125 in bleed and safe area, and leave the keep-clear zone empty. Fonts and images must load from public https links (Google Fonts works).

Merge fields

Every {{tag}} in a design is replaced with the matching value from merge, as plain text. Templates need every one of their fields; a missing field fails with a 422 before anything is made. Values have length limits so they fit the design:

first_name 14promo_code 12last_product 22company 24founder_name 16plan 12update_url 28product_name 22cart_url 28review_url 28

Other fields can be up to 200 characters.

Sizes and credits

Test mail is free. Live mail spends credits from your account, and a request fails with a 402 if the balance doesn’t cover it.

EndpointSize (inches)Credits
/v1/postcards4x6 4×61
/v1/postcards5.5x8.5 5.5×8.52
/v1/postcards6x9 6×92
/v1/postcards6x11 6×112
/v1/flats8.5x11 8.5×113
/v1/flats8.5x14 8.5×143
/v1/flats11x17 11×173

Retrieve and list

GET/v1/postcards/{id}

GET/v1/postcards?limit=25

The same works for /v1/flats. Retrieving returns the full piece with its events. Listing returns { "object": "list", "data": [...] }, newest first, up to 100 per request, for the mode of the key you call with. Check a piece’s status by retrieving it; webhooks aren’t available yet.

curl
curl https://api.mailr.dev/v1/postcards/psc_1f9c2a7e4b10 \
  -H "Authorization: Bearer $MAILR_API_KEY"

curl "https://api.mailr.dev/v1/postcards?limit=25" \
  -H "Authorization: Bearer $MAILR_API_KEY"

Statuses

A piece moves through these statuses. Each step is added to events with a time. Test pieces reach each step on a timer:

StatusMeansTest pieces
queuedQueuedright away
renderedProof readyafter 30 seconds
printedPrintedafter 2 minutes
mailedMailedafter 4 minutes
in_transitIn transitafter 6 minutes
processed_for_deliveryOut for deliveryafter 8 minutes
failedFailedafter 30 seconds, for an undeliverable address

Errors

Errors come back as JSON with a code, a readable message and, for bad input, the field to fix.

HTTPCodeWhen
400invalid_jsonThe body isn’t a JSON object.
401unauthorizedThe key is missing, wrong or revoked.
402insufficient_creditsA live piece costs more credits than the account has.
404not_foundNo piece with that id on your account.
422invalid_requestA field is missing or out of range; field says which.
422 Unprocessable Entity
{
  "error": {
    "code": "invalid_request",
    "message": "tmpl_thank_you needs merge.promo_code.",
    "field": "merge.promo_code"
  }
}

For coding agents

Building with Claude Code, Cursor or Codex? Each template comes with a copy-paste prompt that wires the trigger, the API call and status checks into your codebase. The whole API is also summarized for agents at /llms.txt.

START SENDING

Put your first postcard in the mail

Create a key, send a test to yourself, and check the proof before anything prints.

  • Postcards, flats and folded mailers
  • A proof before anything prints
  • Free test mode: nothing prints, nothing charges
  • A status for every piece