CLI & MCP

@mailcrate/cli is one package with two faces. On a terminal it is a command line: mailcrate push, mailcrate list-campaigns, mailcrate send-email. To an AI agent it is an MCP server: the same operations, exposed as tools, over mailcrate mcp.

Both talk to the same public API over HTTPS with a workspace API key. There is no separate agent API and no server-side setup.

InstallCopy Anchor Link

npm install -g @mailcrate/cli

Or run it without installing:

npx @mailcrate/cli list-campaigns

AuthenticateCopy Anchor Link

mailcrate login --api-key <api_key>

That writes ~/.mailcrate/config.json (mode 0600). In CI, set environment variables instead — they take priority over the file:

export MAILCRATE_API_KEY=<api_key>
export MAILCRATE_API_URL=https://api.mailcrate.io

What it can doCopy Anchor Link

Run mailcrate --help for the current list, and mailcrate <command> --help for one command's flags. Broadly:

The MCP server exposes a curated subset of these; the CLI renders all of them. See MCP server below.

Pushing templatesCopy Anchor Link

The CLI's original job. Point it at a file or a directory of React Email templates; each is matched to Mailcrate by its templateSlug export.

mailcrate push ./emails/
mailcrate push ./emails/welcome.tsx --slug welcome-email
mailcrate push ./emails/ -y          # create missing templates without prompting

Rate limits are handled for youCopy Anchor Link

A push spends two writes per template it has to create, so a large repo can meet the per-key write budget on the Rate Limits page. The CLI waits it out instead of failing: it honours Retry-After, paces itself off X-RateLimit-Remaining before it gets there, and tells you at the end that it was slowed rather than broken.

Done: 30 created, 0 pushed, 0 unchanged, 0 skipped, 0 failed
Slowed by rate limits: waited 24s (3 retried, 2 paused to stay under the limit). This push was slower, not broken — nothing failed because of it.

That line is not a failure and the exit code is still 0; under --json the same information is a throttled block on the result, present only when something was throttled. A key that stays over its limit does eventually give up — after four attempts, or immediately if the API asks for a wait longer than a minute — and says how long it waited before it did.

Machine-readable outputCopy Anchor Link

Every command except login takes --json, which prints the API's raw result and nothing else:

mailcrate list --json | jq -r '.data[].slug'

Failures print { "error": { "message", "statusCode", "body" } } to stderr, with the API's own response body inside — including the class-validator messages that name the field it rejected.

Recipes for CICopy Anchor Link

Stand up a sending domainCopy Anchor Link

Registering a domain returns the DNS records to publish. Registering the same domain twice is safe — you get the existing one back, with its tokens unchanged — so this can live in a provisioning script that runs every deploy.

mailcrate create-sending-domain mail.example.com --json \
  | jq -r '.dnsRecords[] | [.type, .name, .value] | @tsv'

Publish those records, then poll. check-sending-domain-verification exits non-zero until the domain verifies, so a shell loop is the whole implementation:

until mailcrate check-sending-domain-verification "$DOMAIN_ID"; do sleep 30; done
mailcrate create-sender-identity --name "Acme" --email hello@mail.example.com \
  --sending-domain-id "$DOMAIN_ID"

check-hosted-page-domain-verification and check-tracking-domain-verification follow the same exit-code convention.

Two things to know before scripting this: deleting a domain and re-creating it mints new tokens, so every record you published becomes stale; and the public API cannot delete a sender identity, which also means a domain that has one can never be deleted through the API.

Register a webhook endpointCopy Anchor Link

The signing secret is returned once, by create and regenerate-webhook-secret. Every read masks it, so capture it in the same step:

mailcrate create-webhook-endpoint --json \
  --name "CI" --url https://hooks.example.com/mailcrate \
  --subscribed-events delivery.bounced \
  --subscribed-events delivery.complained \
  | jq -r .secret

--subscribed-events is repeatable and validated against the known event names — the API itself accepts any string, so a typo there would subscribe you to an event that never fires.

Send a batchCopy Anchor Link

Batch sending reads a JSON file, because five hundred messages are not something a command line can express. The file is a JSON array of messages, or an object with a messages array; each message takes the same fields as send-email.

mailcrate send-email-batch ./messages.json -y --json | jq '.failed'

The API answers 200 even when individual messages were rejected, so the HTTP status is not the answer. The command exits non-zero if any message failed, and the result carries the index of each failure so you know which one to fix.

Exit codesCopy Anchor Link

0 means the command did what you asked. 1 means it did not — including the cases where the request itself succeeded: a batch with failures, a domain that is not verified yet, a campaign whose preflight refused to send. That is what makes && and until work without parsing output.

MCP serverCopy Anchor Link

mailcrate mcp speaks the Model Context Protocol over stdin and stdout, so an agent can work your workspace directly. For an agent that cannot start a local process — claude.ai, Managed Agents — use the hosted MCP server instead.

Register it once:

claude mcp add mailcrate -- mailcrate mcp

The equivalent JSON, for any client that configures MCP servers that way:

{
  "mcpServers": {
    "mailcrate": {
      "command": "mailcrate",
      "args": ["mcp"],
      "env": {
        "MAILCRATE_API_KEY": "<api_key>",
        "MAILCRATE_API_URL": "https://api.mailcrate.io"
      }
    }
  }
}

What the agent seesCopy Anchor Link

Each tool carries the same description a human gets from --help, plus annotations describing what it does:

• readOnlyHint — the tool changes nothing (find_contact, get_campaign, render_template_preview).
• destructiveHint — the tool can cause mail to leave, or change something that cannot be put back (send_email, send_campaign, enroll_contact).

Not every command is exposed as a tool. create-email-template is left out because push creates missing templates itself, and a tool whose only use is making an empty template an agent then has to remember to fill is a way to get half-finished templates rather than mail.

push is available here — it reads files from the machine the server runs on, which is your own machine in the stdio case. That is also why it will not appear on the hosted MCP server, where the filesystem is ours.

What a tool returnsCopy Anchor Link

The API's JSON result, compactly serialised — no pretty-printing, because the indentation would be paid for out of the agent's context window and read by a parser rather than a person.

A single value longer than 20,000 characters is cut short and marked inline with …[truncated], and the response carries a second note saying so. In practice that only affects render-template-preview and render-html-preview, which return a whole email's HTML. The number of items in a list is governed by limit, not by this.

Irreversible tools need explicit confirmationCopy Anchor Link

Annotations are advisory — the MCP specification says clients should not make tool-use decisions based on them, and not every client shows them at all. So anything that sends mail additionally takes a confirm parameter and refuses to run without confirm: true — whether it was set to false or left out altogether:

{
  "error": {
    "message": "send_email makes changes that cannot be undone, so it requires confirm: true. Re-send the same arguments with confirm set to true if that is what you intend.",
    "statusCode": null,
    "body": null
  }
}

A model cannot send your campaign by accident; it has to state in the arguments that it meant to.

Which key to give an agentCopy Anchor Link

The server can only do what its key can do, so the key is the real control.

• Exploring, reporting, drafting — a read-only key. Grant the :read scopes for the areas the agent should see (contact:read, campaign:read, delivery:read, email-template:read). Write tools still appear in the tool list, but the API rejects them with a 403 naming the missing scope, and the agent sees that verbatim.
• Sending — add only the write scopes you actually intend, such as sending:write for transactional mail.
• full_access — only when the agent is genuinely meant to do everything, and only for a first-party integration you trust. It bypasses every per-resource check.

See API Keys & Scopes for the full list.