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 happens | Mail this |
|---|---|
| An order's status changes to shipped | A thank-you card with a code for the next order. (First-order thank you) |
| 21 days after delivery | A 4x6 review request with a short link. (Review request) |
| A new account confirms its email | A founder welcome letter a few days later. (Welcome letter) |
Set it up
- 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.
- 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.
- 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.
- 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.