Email infrastructure

EmailMate Docs

Rails for agents and humans who build email products. REST for apps, MCP for agents, dashboard for operators. Same domains, keys, logs, and reputation. SES under the hood.

Platform

Three doors on one send stack. Use cases (newsletters, ship notes, outreach) are things you build — not separate products.

Quickstart

Verify a domain → mint a domain-scoped key → send. Target under 15 minutes.

1. Install the SDK

bun add emailmate
# npm install emailmate

2. Send (Resend-shaped)

import EmailMate from "emailmate";

const em = new EmailMate(process.env.EMAILMATE_API_KEY!);

const { id } = await em.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Welcome",
  html: "<p>You're in.</p>",
  text: "You're in.",
});

3. curl

curl https://www.emailmate.dev/v1/emails \
  -H "Authorization: Bearer em_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "user@example.com",
    "subject": "Welcome",
    "html": "<p>Hi</p>",
    "text": "Hi"
  }'

4. Coming from Resend?

// Before
import { Resend } from "resend";

// After — drop-in class export
import { Resend } from "emailmate";

const resend = new Resend(process.env.EMAILMATE_API_KEY!);
await resend.emails.send({ from, to, subject, html });

Authentication

Every REST call needs a Bearer key. Keys start with em_ (legacy re_ / ml_ still resolve). Prefer domain-scoped keys — From ownership is fail-closed.

Authorization: Bearer em_xxxxxxxxxxxx
Content-Type: application/json

Sending rules

Production lessons, enforced so Gmail stays green.

// Transactional (OTP, receipts)
await em.emails.send({
  from: "Acme <hello@acme.com>",
  to, subject, html, text,
  // omit bucket
});

// Marketing one-shot via API
await em.emails.send({
  from: "Acme <jimmy@mail.acme.com>",
  to, subject, html, text,
  bucket: "marketing",
  reply_to: "jimmy@mail.acme.com",
});

MCP for agents

Agent-native surface mirrors REST. Default URL is rails only (send, domains, logs, keys). Inbox tools need https://mcp.emailmate.dev/mcp?sets=inbound. OAuth consent at https://www.emailmate.dev/oauth/mcp, or Bearer key on Streamable HTTP.

claude mcp add --transport http emailmate https://mcp.emailmate.dev/mcp

// .cursor/mcp.json
{
  "mcpServers": {
    "emailmate": {
      "type": "http",
      "url": "https://mcp.emailmate.dev/mcp"
    }
  }
}

Core

Transactional send

Send, batch, domains, keys, templates, webhooks, suppressions. This is the product.

Send email

Programmatic transactional mail — OTP, receipts, product notifications. Response shape is Resend-compatible: { "id": "…" }.

{
  "from": "Acme <hello@acme.com>",
  "to": ["user@example.com"],
  "subject": "Your code is 482910",
  "html": "<p>482910</p>",
  "text": "482910",
  "tags": [{ "name": "category", "value": "otp" }]
}

Batch send

Send up to 100 messages in one request (Resend batch shape).

[
  { "from": "Acme <hello@acme.com>", "to": "a@x.com", "subject": "Hi", "html": "<p>A</p>" },
  { "from": "Acme <hello@acme.com>", "to": "b@x.com", "subject": "Hi", "html": "<p>B</p>" }
]

Templates

CRUD templates in the API, or use registry templates from emailmate/templates (React Email). Send with template + data on POST /emails.

// POST /v1/emails with template
{
  "from": "Acme <hello@acme.com>",
  "to": "user@example.com",
  "template": "welcome",
  "data": { "name": "Ada" }
}

Domains

Add domain → publish SPF, DKIM, MAIL FROM → verify. Status until verified. Add DMARC (p=none OK to start) before scale.

Bring your own SES

EmailMate is a SES plugin. Cloud uses our AWS account. BYOK uses yours. Same REST, MCP, and desk. Resend does not let you plug in keys.

IAM

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ses:SendEmail",
      "ses:SendRawEmail",
      "ses:GetAccount",
      "ses:CreateEmailIdentity",
      "ses:DeleteEmailIdentity",
      "ses:GetEmailIdentity",
      "ses:PutEmailIdentityMailFromAttributes"
    ],
    "Resource": "*"
  }]
}

Self-host later

The same plugin reads AWS_SES_* env vars. Connecting keys in the desk is the cloud form of that plugin.

API keys

Create in dashboard or API. Domain-scoped keys can only send From that domain.

Webhooks

Customer endpoints for delivery events — Resend-style CRUD. Secret whsec_… returned once on create. SES system ingestion is separate: POST /v1/webhooks/ses (no Bearer).

{
  "name": "Prod",
  "url": "https://app.example.com/hooks/email",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ]
}

Events

Inbox

Named mailboxes on your verified domain. Enable receive on the domain page (Cloudflare Email Routing catch-all). Create agent@your-domain — or omit the username for a random local-part. Unknown addresses land in catch-all (receive-only). Reply and send go out via SES. MCP inbox tools are opt-in: https://mcp.emailmate.dev/mcp?sets=inbound.

Suppressions

Hard bounces and complaints auto-suppress. Marketing respects bucket prefs. Never re-mail suppressed addresses.

GDPR

Export and erase paths for compliance workflows.

Lists

Campaigns

Send one HTML to a list. Always from a marketing subdomain. List-Unsubscribe is automatic on broadcasts. Not a Mailchimp replacement — list-send on the same rails as OTP.

Audiences

Named lists for campaigns and newsletters.

Contacts

Nested under audiences (Resend / Mailchimp-style). Supports first/last name and unsubscribed flag. Import merges on duplicate email where enabled.

{
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace"
}

Segments

Mailchimp-style filters over an audience. AST: { op: "and"|"or", clauses: [{ field, cmp, value }] }. Broadcasts may target a segment_id when supported on the desk.

{
  "name": "VIPs",
  "audience_id": "aud_…",
  "filter": {
    "op": "and",
    "clauses": [{ "field": "tag", "cmp": "eq", "value": "vip" }]
  }
}

Campaigns (broadcasts)

Create a draft → send now or schedule. Sends use the marketing bucket + List-Unsubscribe. From domain must be verified.

{
  "name": "Launch",
  "subject": "We're live",
  "audience_id": "aud_…",
  "from": "Jimmy <jimmy@mail.acme.com>",
  "html": "<p>Ship day.</p>",
  "preview_text": "Ship day",
  "reply_to": "jimmy@mail.acme.com"
}

// optional body
{ "scheduled_at": "2026-08-01T15:00:00.000Z" }

const b = await em.broadcasts.create({
  name: "Launch",
  audience_id: "aud_…",
  from: "Jimmy <jimmy@mail.acme.com>",
  subject: "We're live",
  html: "<p>Ship day.</p>",
});
await em.broadcasts.send(b.id);

Use case

Newsletter APIs

Publications and issues exist so hosts can build a newsletter. EmailMate is the rails, not Beehiiv.

Publications

{
  "name": "Weekly Ship",
  "from_name": "Acme",
  "from_email": "jimmy@mail.acme.com",
  "slug": "weekly-ship",
  "public_subscribe": true,
  "double_opt_in": false
}

Issues

Draft issues → send to the publication audience. Status: draft · scheduled · sending · sent · cancelled.

const nl = await em.newsletters.create({
  name: "Weekly Ship",
  from_name: "Acme",
  from_email: "jimmy@mail.acme.com",
  public_subscribe: true,
});
const issue = await em.newsletters.createIssue(nl.id, {
  title: "Issue 12",
  subject: "What shipped this week",
  html: "<p>…</p>",
});
await em.newsletters.sendIssue(issue.id);

Subscribe pages

When public_subscribe is true, the publication is live at:

No embed iframe required for MVP — share the URL. Double opt-in sends a confirm message when enabled.

Use case

Ship notes

Product updates are a campaign, not a product. Same POST /v1/broadcasts path, marketing domain, one-click unsub.

Use case

Outreach

Cold send with daily caps on the marketing domain. You build the product; we provide the rails.

Cold campaigns

Daily caps protect reputation. Marketing domain only. Start queues min(list, daily_cap) via the marketing path. Cap clamped 1–500 (default 50).

{
  "name": "Builder intros",
  "subject": "Quick question",
  "audience_id": "aud_…",
  "from_name": "Jimmy",
  "from_email": "jimmy@mail.acme.com",
  "daily_cap": 50,
  "html": "<p>…</p>",
  "notes": "opt-in list only"
}

SDK

Official TypeScript client. Resources: emails · domains · inboxes · apiKeys · templates · webhooks · audiences · contacts · segments · broadcasts · newsletters · outreach · suppressions · gdpr.

import EmailMate from "emailmate";

const em = new EmailMate(process.env.EMAILMATE_API_KEY!);

// Transactions
await em.emails.send({ from, to, subject, html, text });

// Inbox (named mailbox on a verified domain)
const box = await em.inboxes.create({ domain: "acme.com", username: "agent" });
await em.inboxes.messages.send(box.id, { to, subject, text });

// Segments
await em.segments.create({
  name: "VIPs", audience_id, filter: { op: "and", clauses: [{ field: "tag", cmp: "eq", value: "vip" }] },
});

// Marketing
const b = await em.broadcasts.create({
  audience_id, from: "Name <mail@domain.com>", subject, html,
});
await em.broadcasts.send(b.id);

// Newsletter
const nl = await em.newsletters.create({
  name: "Weekly", from_name: "Acme", from_email: "jimmy@mail.acme.com",
});
const issue = await em.newsletters.createIssue(nl.id, { title: "Ship notes", html });
await em.newsletters.sendIssue(issue.id);

// Outreach
const o = await em.outreach.create({
  name: "Cold A", subject, audience_id,
  from_name: "Jimmy", from_email: "jimmy@mail.acme.com", daily_cap: 40,
});
await em.outreach.start(o.id);

Rate limits

Per API key, by plan. Exceeded → 429 with Retry-After. Agent keys on Free are stricter.

Errors

JSON error bodies. Honor status codes for retries.

{
  "statusCode": 422,
  "message": "Domain not verified",
  "name": "validation_error"
}

OpenAPI

Machine-readable contract for codegen, agents, and Scalar UI.