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

Cursor direct mail: a project rule and a skill for postcards

Cursor direct mail starts with two files: a project rule in .cursor/rules with your conventions and the Mailr skill in .cursor/skills with the API. Ask Agent to mail a postcard when something happens in your app, and it writes the trigger, the request and a test against a free key.

What to mail from Cursor

When this happensMail this
An order's status changes to shippedA thank-you card with a code for the next order. (First-order thank you)
21 days after deliveryA 4x6 review request with a short link. (Review request)
A new account confirms its emailA founder welcome letter a few days later. (Welcome letter)

Set it up

  1. Add the skill under its own name. Copy the skill from https://mailr.dev/downloads/mailr-kit.zip into .cursor/skills/mailr-direct-mail/. Cursor requires the folder name to match the skill's name field, which is mailr-direct-mail. Agent applies it when a task is about mail, or you can call it with /mailr-direct-mail.
  2. Add a project rule. Save the rule below as .cursor/rules/mailr.mdc. With a description and alwaysApply: false, Agent pulls it in when a task is about mail. Only .mdc files count in that folder; a plain .md file there is ignored.
  3. Let the sandbox reach the API. Agent runs terminal commands in a sandbox where the network is blocked except for an allowlist. Add api.mailr.dev to networkPolicy.allow in .cursor/sandbox.json so its test request gets through.
  4. Ask Agent, then go live. Put a test key in .env as MAILR_API_KEY and describe the feature. When the test piece reaches processed_for_delivery (about 8 minutes), add funds and swap in the live key.

Cursor setup

---
description: Sending physical mail (postcards, letters) through the Mailr API
alwaysApply: false
---

- Mail goes through the Mailr API, https://api.mailr.dev/v1. Use the
  mailr-direct-mail skill for endpoints, sizes, templates and clear zones.
- Read the key from MAILR_API_KEY in server code only. Use the test key
  (mlr_test_...) in dev and tests; never switch to a live key yourself.
- Send an Idempotency-Key on every POST, built from the record and the event,
  e.g. thank-you-<order_id>.
- Store the returned piece id on the record (orders.mailr_piece_id) and skip
  records that already have one.
- No webhooks: check status with GET /v1/postcards/{id} or /v1/flats/{id}.
  • Cursor also reads AGENTS.md in the repo root, so a Mailr section you wrote for Codex works here too.
  • Skills load from .cursor/skills and .agents/skills, and for compatibility from .claude/skills and .codex/skills. One copy in .agents/skills/mailr-direct-mail serves both Cursor and Codex.
  • Merge values have length caps (first_name 14 characters, product_name 22). A longer value fails with a 422 before anything prints, so have Agent trim or fall back.

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: First-order thank you (6x9), Review request (4x6), Welcome letter (8.5x11).

Questions

Rule or skill: which one does the work?

Both. The skill carries Mailr's reference: endpoints, sizes, clear zones and templates. The rule carries your project's choices: which env var, the idempotency key format, where piece ids are stored.

Is there a Mailr MCP server for Cursor?

Not yet. Agent calls the REST API from your code, guided by the skill. The whole API is also in one file at https://mailr.dev/llms.txt.

Can Agent change a template's design?

Yes. Each template in the kit has front.html, back.html and a template.json with the bleed, safe area and keep-clear zone. Ask Agent to copy them into your repo, edit them, and send them as front and back.

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.
CURSOR

Mail from Cursor 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.