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

Codex direct mail: give Codex the API and your rules

Codex direct mail needs two files in your repo: the Mailr skill in .agents/skills and a short section in AGENTS.md that says where the key lives and how retries work. Then you ask Codex for the feature, and it writes the job, the request and a test against a free key.

What to mail from Codex

When this happensMail this
A customer's last order turns 60 days old (nightly job)A win-back postcard with a code, sent as one batch per 1,000 people. (Win-back)
A checkout is still open after 48 hoursThe product they left behind, on a 6x9 card with the cart link. (Abandoned cart)
A card fails its last Stripe retryA plain billing letter, mailed flat, after the emails didn't work. (Failed payment)

Set it up

  1. Add the skill. Download https://mailr.dev/downloads/mailr-kit.zip and copy skills/mailr-direct-mail into .agents/skills/; the folder carries the templates and blank layouts with it. Codex scans .agents/skills from the folder it's working in up to the repo root, picks the skill up on its own when a task is about mail, and you can call it by name with $mailr-direct-mail.
  2. Write your rules in AGENTS.md. Codex reads AGENTS.md files from the repo root down to the folder it's working in, before it starts. Add a short Mailr section: the env var that holds the key, how to build the Idempotency-Key, and where piece ids get saved.
  3. Let the sandbox reach api.mailr.dev. In the CLI and IDE extension, the default workspace-write sandbox has no network, so the agent's test request fails. Set network_access = true under [sandbox_workspace_write] in ~/.codex/config.toml, or approve the request when Codex asks to step outside the sandbox.
  4. Ask, test, then go live. Put a test key in MAILR_API_KEY and describe the feature. Test pieces are free, never print, and walk through every status in about 8 minutes. When it works, add funds and swap in the live key yourself.

Codex setup

## Mail (Mailr)

- We send postcards and letters through the Mailr API (https://api.mailr.dev/v1).
  Reference: .agents/skills/mailr-direct-mail/SKILL.md and https://mailr.dev/llms.txt
- The key is in MAILR_API_KEY. Build and test with a test key (mlr_test_...).
  Never hard-code a key and never switch to a live key yourself.
- Every POST sends an Idempotency-Key made from the record and the event,
  e.g. abandoned-cart-<checkout_id>. For a batch, use a hash of its recipient ids.
- Save the returned piece id on our record and check it before sending,
  so nobody gets the same piece twice.
- Mailr has no webhooks. Read status with GET /v1/postcards/{id} or /v1/flats/{id}.
- More than 1,000 recipients: split into several POST /v1/batches requests.
  • Codex cloud tasks: environment variables last for the whole task, but secrets are removed before the agent phase starts, so a test key the agent has to use goes under Environment variables. Agent internet access is off by default; turn it on, add api.mailr.dev to the domain allowlist, and don't limit it to GET, HEAD and OPTIONS, or the POST is blocked.
  • AGENTS.md files share a 32 KiB limit by default (project_doc_max_bytes). Point to the skill and https://mailr.dev/llms.txt rather than pasting the whole API into AGENTS.md.
  • Copy the skill into a folder named after its name field, mailr-direct-mail. The same .agents/skills folder is also read by Cursor, which requires the two to match.

What it costs

Each live piece is paid from your Mailr balance, printing and postage included: a 4x6 postcard is $0.85, a 6x9 $0.89 and an 8.5x11 letter $0.95 on pay as you go, less on a plan. Test pieces are free. All prices.

Templates that fit: Win-back (6x11), Abandoned cart (6x9), Failed payment (8.5x11).

Questions

Does Codex need an MCP server to send mail?

No, and Mailr doesn't have one yet. Codex writes plain HTTPS calls to https://api.mailr.dev/v1 in your code, guided by the skill and https://mailr.dev/llms.txt.

Will Codex print real mail while it's testing?

Not with a test key. mlr_test_ keys never print or charge. Keep the live key out of the environment Codex runs in until you're ready; the AGENTS.md rule also tells it never to switch keys on its own.

How does my app find out a piece was mailed?

Mailr has no webhooks yet. Save the id and read GET /v1/postcards/{id} (or /v1/flats/{id}) when you need it. The events list has every status with a time.

The code on this page is written against the Mailr API as it works today. Test it with your test key first; nothing prints until you use a live key.
CODEX

Mail from Codex today

Get a free test key, send one postcard to yourself and watch it move through every status.

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

Download the template kit?

mailr-kit.zip · about 190 KB · 47 text files

Only HTML, JSON and Markdown files. No programs, scripts or macros, nothing that installs or runs.