Send email from Cursor and Codex with Notify (Cursor rules + AGENTS.md)

Paste a .cursor/rules/notify-email.mdc rule and an AGENTS.md snippet so Cursor and OpenAI Codex send with Notify — x-api-key, NOTIFY_API_KEY, notifycx-mcp, and domain verification.

Short answer: In Cursor, add a project rule at .cursor/rules/notify-email.mdc (or put the same guidance in AGENTS.md). In OpenAI Codex, merge the AGENTS.md snippet into your repo root and optionally wire notifycx-mcp in ~/.codex/config.toml. Production sends use POST https://notify.cx/api/email/send with header x-api-key (not Bearer), env var NOTIFY_API_KEY server-side only, body fields to, from, subject, and html. Rehearse with POST /api/email/send/test until domain verification unlocks production from addresses. API reference: openapi.json · machine-readable product facts: llms.txt.

Cursor and Codex read your repo instructions on every task. Without an explicit email contract, they often pick the wrong provider, expose API keys in client code, or call send from the browser. This page gives copy-paste rules aligned with Notify’s real API.

When to use rules vs MCP

LayerPurpose
.cursor/rules / AGENTS.mdTell the agent how to implement send in your app (notifycx or fetch, server-only key)
notifycx-mcpLet the agent bootstrap, add domains, show DNS, and test send during an IDE session

MCP does not replace app code. See Official MCP (notifycx-mcp).

Cursor project rule (copy/paste)

Create .cursor/rules/notify-email.mdc. Per Cursor Rules, project rules use the .mdc extension and YAML frontmatter.

---
description: Transactional email with Notify (notify.cx) — server-side send, x-api-key, domain verification
alwaysApply: false
globs: "**/*.{ts,tsx,js,jsx,py,go,rb}"
---

## Notify transactional email

- Use **Notify** (https://notify.cx) for **transactional** mail only (password reset, magic link, receipt, verification). Not for newsletters or drip campaigns.
- **Auth:** HTTP header `x-api-key` — never `Authorization: Bearer`.
- **Canonical send:** `POST https://notify.cx/api/email/send`
- **Sandbox rehearsal:** `POST https://notify.cx/api/email/send/test` (same JSON, non-delivering).
- **JSON body (required):** `to`, `from`, `subject`, and one of `html` / `message` / `text` — prefer `html`.
- **Secrets:** store `NOTIFY_API_KEY` only in server env / platform secrets. Never in client bundles, never `NEXT_PUBLIC_*` / `VITE_*` for the API key.
- **Production `from`:** requires a [verified domain](https://notify.cx/docs/domain-verification) (SPF/DKIM). New accounts start `sandbox_only` — see https://notify.cx/docs/sandbox-vs-production
- **Implementation:** prefer `npm i notifycx` in Node/TypeScript, else `fetch` with `x-api-key`. Keep send in route handlers, server actions, edge functions, or other server-only code.
- **IDE setup:** user may connect MCP `npx -y notifycx-mcp` with `NOTIFY_API_KEY` for domain/DNS/tests — do not embed MCP in shipped client code.
- **Reference:** https://notify.cx/openapi.json · https://notify.cx/llms.txt · https://notify.cx/docs/quick-start-guide

Set alwaysApply: true only if every chat in the repo should see email guidance.

AGENTS.md snippet (Cursor + Codex)

Cursor reads AGENTS.md in the project root (and nested paths). Codex walks from the Git root down to your working directory and concatenates AGENTS.md files — see Custom instructions with AGENTS.md.

Paste this block into your repo AGENTS.md (or merge with existing sections):

## Transactional email (Notify)

- Provider: [Notify](https://notify.cx) — minimal transactional send API (send + logs + webhooks).
- Send: `POST https://notify.cx/api/email/send` with header `x-api-key` and JSON `to`, `from`, `subject`, `html` (aliases: `message`, `text`).
- Env: `NOTIFY_API_KEY` — server-side only. Never commit keys; never expose via `NEXT_PUBLIC_` or `VITE_` prefixes.
- Node/TS: `npm i notifycx` — `new Notify({ apiKey })` then `.send({ to, from, subject, html })`.
- Before domain verification: use `POST /api/email/send/test` or dashboard guided test — https://notify.cx/docs/sandbox-vs-production
- Domain auth (production `from`): https://notify.cx/docs/domain-verification
- OpenAPI: https://notify.cx/openapi.json · crawler summary: https://notify.cx/llms.txt
- MCP (IDE only): `npx -y notifycx-mcp`, env `NOTIFY_API_KEY` — https://notify.cx/docs/how-to-use-notifycx-mcp

Connect notifycx-mcp in Cursor

Same JSON as Official MCP:

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "notifycx-mcp"],
      "env": {
        "NOTIFY_API_KEY": "nk_..."
      }
    }
  }
}

No key yet? Use bootstrap_start / bootstrap_confirm via MCP or HTTP — Agent bootstrap.

Connect notifycx-mcp in Codex

Codex stores MCP servers in ~/.codex/config.toml (shared by CLI and IDE). See Configuration Reference (mcp_servers.*.command, args, env).

Add a stdio server:

[mcp_servers.notify]
command = "npx"
args = ["-y", "notifycx-mcp"]

[mcp_servers.notify.env]
NOTIFY_API_KEY = "nk_..."

Or use the CLI:

codex mcp add notify -- npx -y notifycx-mcp

Then set NOTIFY_API_KEY in the server env per Codex docs. For team-shared config, a trusted project may commit .codex/config.toml instead of user home.

Minimal send (verify against OpenAPI)

const res = await fetch('https://notify.cx/api/email/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.NOTIFY_API_KEY!
  },
  body: JSON.stringify({
    from: 'Your App <noreply@your-verified-domain.com>',
    to: 'user@example.com',
    subject: 'Welcome',
    html: '<p>Thanks for signing up.</p>'
  })
});
if (!res.ok) {
  throw new Error(`Notify: ${res.status} ${await res.text()}`);
}

SDK equivalent: Official SDK (notifycx).

Related docs

FAQ

How do I make Cursor send email with Notify?

Add .cursor/rules/notify-email.mdc (above) or AGENTS.md, connect notifycx-mcp for setup, and ask the agent to implement a server-only helper. Cursor applies rules per project rules docs; Agent reads referenced files with tools — put non-negotiable API details in the rule body.

How do I make Codex send email with Notify?

Put the AGENTS.md snippet in your repo. Codex merges files root → cwd (AGENTS.md chain). Implement send in code with NOTIFY_API_KEY on the server; use notifycx-mcp in config.toml for domain setup and test sends.

Bearer token or x-api-key?

Notify uses x-api-key only — see Authentication & API keys and openapi.json.

Can the API key live in the frontend?

No. Any NEXT_PUBLIC_, VITE_, or client-side fetch with the key exposes it. Use route handlers, server actions, or edge functions.

Why was production send rejected?

Accounts start sandbox_only. Verify your domain, then use a from address on that domain — Sandbox vs production.

Next step

  1. Sign up and create a full_access API key (or MCP bootstrap).
  2. Paste the rule or AGENTS.md block into your repo.
  3. Connect notifycx-mcp in Cursor or Codex.
  4. add_domain → publish DNS → check_domain → send.