Mailtea

View saved version →

---
name: mailtea-email
description: Send, schedule, and manage email with Mailtea from an AI agent. Use when the user wants to send a transactional email, send a batch, schedule a send, check delivery status / opens / clicks, list or cancel emails, manage contacts/segments, or draft and send a newsletter — via the Mailtea MCP server, the mailtea Node SDK, or the REST API.
---

# Mailtea email

Mailtea lets you send and manage email programmatically. Prefer the **MCP server**
(no code) when it's connected; fall back to the **SDK** or **REST** in code.

> **Designing** the email rather than sending it? Use **mailtea-email-design**
> first — it covers how the email should *look* and survive real inboxes, and the
> structured ops path that is faster than writing HTML. Building the publication's
> public **website**? Use **mailtea-site-design**.

## Setup (once)

If Mailtea MCP is already connected, use it directly. Call `auth.me` and
`publication.list` to check the account and available publications. A browser
sign-in connects you to ONE publication — the one the user picked on the consent
screen — so `publicationId` is optional on every tool and defaults to it. Pass
one only when the connection reaches several publications; ask which to use when
that is the case and the request is ambiguous, and never guess across accounts.

If it is not connected, tell the user to connect Mailtea in their agent client
(browser sign-in; never paste credentials in chat). They sign in to Mailtea and
choose the publication and permissions on the consent screen. The hosted MCP
server is `https://api.mailtea.app/mcp`.

### Reconnecting per client

| Client | How to reconnect |
| --- | --- |
| Codex | `codex mcp login mailtea` |
| Claude Code | `/mcp`, then Mailtea, then Authenticate — or `claude mcp login mailtea` |
| Claude.ai | Settings, Connectors, Mailtea, Reconnect |
| Cursor | Cursor Settings, MCP, Mailtea, Reconnect (Grok Bot shares it) |
| VS Code | Command Palette, **MCP: List Servers**, Mailtea, then Start or Authenticate |
| Kiro | MCP settings, Mailtea, Reconnect |
| Grok Build | `/marketplace` and choose Mailtea, or reconnect from `grok mcp` |
| ChatGPT | Settings, Apps & Connectors, Mailtea, Reconnect |

For a local stdio connection, get a personal access token (prefix `mt_pat_`, or `mt_test_` for a test key) from Mailtea Studio
(**Settings → API keys**) or `POST /v1/api-keys`. Then connect Claude Code:

```bash
claude mcp add mailtea -e MAILTEA_API_TOKEN=mt_pat_xxx -- npx -y mailtea-mcp
```

Self-hosting or local dev? add `-e MAILTEA_API_BASE_URL=http://localhost:7787`.

## Guide a first-time user

For “help me get started” or “help me send my first email”, explain the next
useful step in plain language. A publication is the workspace for their email,
audience, and website; do not assume the user knows that term.

1. If the connection is missing, direct the user to connect Mailtea in their
   agent client. Use the browser sign-in flow; never ask for passwords or
   tokens in chat.
2. Read `auth.me` and `publication.list`. If exactly one publication comes back,
   that is the connected one and every tool defaults to it — do not ask. Use the
   publication the user named; otherwise ask them to choose when more than one is
   available. If none is accessible, explain whether they need to create a
   publication in Mailtea Studio or reconnect with access to an existing one.
3. Read `sender.list` and `domain.list`, using the live tool schemas. Omit
   `publicationId` to use the connected publication; pass it only when the user
   picked one of several. Show available sender addresses without exposing credentials.
   If the domain or DKIM is unverified, explain the missing verification and link
   to https://docs.mailtea.app/docs/documentation/domains. Do not change DNS or
   create senders just because the user asked to check setup.
4. Ask only for missing sender, recipient, subject, body, or schedule details.
   Batch missing details into 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: mailtea-email-design
description: Design a beautiful, on-brand, deliverable email, newsletter or template in Mailtea. Use when an agent is about to build or restyle a Mailtea email — covers the structured block/ops path (fastest, email-safe by construction), hand-written email-safe HTML when you own the whole document, images, brand colour, and the render/QA loop. Pairs with the mailtea-email skill (which covers sending/managing) — this one covers how the email should LOOK.
---

# Mailtea email design

`mailtea-email` teaches you how to *send*. This teaches you how to make the email
*look good* — and survive real inboxes. Email is not the web: no flexbox, no CSS
variables, no web fonts you can rely on, and Outlook renders with Word.

## Choose your path first — one of these is much faster

| | **A. Ops (structured blocks)** — prefer this | **B. Hand-written HTML** |
|---|---|---|
| You write | Declarative blocks: `{kind:"heading",…}`, `{kind:"button",…}` | Tables, inline styles, media queries |
| Email-safety | **By construction.** The reducer only emits nodes that survive an inbox; it cannot produce `display:flex` | **Yours to get right** — see the contract below |
| Editing later | Surgical: address one block by path and change it | Re-emit the whole document |
| The operator | Keeps editing it as normal blocks in the Visual Email Designer | Opens as one "Custom HTML" block |
| Use for | Newsletters, broadcasts, anything an operator will touch again | Pixel-controlled transactional designs (receipts) where YOU own the whole layout |

**Default to A.** Reach for B only when you genuinely need a complete
`<!DOCTYPE html>` document. If you are doing B, skip to *The email-safe contract*.

## A. The ops path

### The loop

```
issue.create_draft  →  issue.apply_ops (compose + set_styles + set_headers)
                    →  email.lint      →  issue.preview / posts send-test
                    →  issue.apply_ops (edit_text / edit_block / arrange) to refine
```

`issue.apply_ops` takes a batch and returns a **report**: `applied`, `skipped`
(each with a reason), and — after any structural op — a fresh **outline**. Read
the report. It is the correction signal; nothing fails silently.

### Address blocks by path, from the outline

Paths are dot-joined child indexes: `0.3`, `0.12`. **Always read the outline from
the last response (or `issue.get_editor`) before addressing anything.** Never
carry paths across turns without re-reading — the tree moves when blocks are
added or removed.

```bash
mailtea call issue.get_editor --json '{"issueId":"iss_…"}'   # → outline, styles, headers
```

### Ops

| op | what it does |
|---|---|
| `compose` | Replaces the whole body. Establishes the editor's root wrapper, so paths start `0.0`, `0.1`, … and stay put. |
| `insert_blocks` | Adds blocks at `path` + `position` (`before`/`after`/`append-into`); no path = append to the end. |
| `edit_text` | Rewrites one block's copy: `{edits:[{path,text}]}`. |
| `edit_block` | Sets one block's attributes: `{path, expectType, attrs}`. |
| `set_styles` | The email's look, as flat tokens (below). |
| `arrange` | `moves` then `deletes`. Addresses resolve against the doc as it stands when this op runs, so an earlier `insert_blocks` or `arrange` in the same batch has already shifted them. Give every delete an `expectType` (`{path, expectType}`): if any address in the op is stale, the whole op is refused and nothing is deleted. |
| `set_headers` | `subject` and `previewText` (the inbox preheader). |

### Block kinds

`heading` (text, level 1-3) · `text` · `bulletList` / `numberedList` (items) ·
`quote` · `button` (label, href, alignment, variant) · `image` (src, alt,
alignment) · `divider` · `spacer` (height) · `columns` · `section` · `footer` ·
`html` · `variable` (key, fallback).

Text fields take inline markup — `**bold**`, `*italic*`, `[label](https://url)` —
and nothing else. **A `\n` inside one text block becomes a line break**; for two
visually separat

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: mailtea-site-design
description: Build and restyle a publication's public website with Mailtea from an AI agent — pages, sections, theme, and the design brief that keeps later edits on-brand. Use when the user wants to create or change their Mailtea site (home, about, archive, a landing page), restyle it, or publish it. Pairs with mailtea-email-design, which covers the email side.
---

# Mailtea site design

Every Mailtea publication has one public website: a home page, an archive of
posts, and whatever else you add. It is edited the same way an email is — a
declarative ops batch against a draft, then a deliberate publish.

**Ops go to the DRAFT.** Real visitors keep seeing the live site until someone
calls `site.publish`. That is the safety net, so use it: build, look, fix, and
only publish when the user asks. `site.page_upsert` is the exception: it writes
live (see Pages).

## The loop

```
site.get                 → what exists: pages, theme, live vs draft
site.section_templates_list        → the section templates you can insert (use these, don't invent)
site.design_brief_set    → the durable intent, once (below)
site.apply_ops           → compose / insert / edit / arrange / theme / navbar / rename
site.publish             → make it real  ← only when the user asks
```

`site.discard_draft` throws away **every** pending draft edit across the whole
site, including the operator's own unpublished work. Destructive and not
undoable — confirm before calling it.

## Ops

`site.apply_ops` takes `{pageId, ops, baseVersion}` and reports
what applied and what was skipped, same contract as the email reducer.

Every site tool also accepts `publicationId`, but it is optional: it defaults to
the publication the connection is for. Pass it only when the connection reaches
more than one.

| op | what it does |
|---|---|
| `compose_page` | Replaces a page's whole section list. |
| `insert_section` | Adds a template section at `index`, with `copy` for its text slots. |
| `swap_section` | Replaces one section with a different template, carrying the copy across. |
| `edit_copy` | Rewrites text: `{edits:[{nodeId, …}]}`. |
| `edit_style` | One node's `style` / `layout`. |
| `arrange` | `moves` then `deletes`. |
| `set_navbar_template` | `templateId` from `site.navbar_templates_list`, optional `brand`. Replaces the navbar. |
| `rename_nodes` | `renames: [{nodeId, layerName}]`. Layer-tree labels only — nothing a visitor sees. |
| `set_theme` | Site-wide design tokens. |

Sections are addressed by **`nodeId`**, not by index path — ids are stable across
edits, so unlike the email reducer you can safely hold one across turns. Get them
from `site.page_get`.

Prefer `insert_section` with a **template** over composing raw structure: templates
are the vocabulary the theme knows how to style, so a template section inherits the
site's design and a hand-built one drifts from it.

## Pages

`site.page_upsert` needs `{kind, slug, title}` and optionally
`status`, `contentJson`, and the SEO fields (`seoTitle`, `seoDescription`,
`seoOgImageUrl`). Write the SEO fields — a page shared without them gets an ugly
unfurl, and nobody goes back to add them later.

`site.page_upsert` writes the page's **live** document, not the draft. A
published page changes for visitors at once, with no preview. If the page has a
pending draft (`hasDraft` on `site.page_get`), that draft is kept: `site.page_get`
keeps returning it, and the next `site.publish` replaces your upsert with it.
For edits that should wait for review, use `site.apply_ops`.

## The design brief

`site.design_brief_set` stores the site's durable design intent — audience, tone,
palette, the feel. Set it **before** a big design pass and every later edit,
yours or another agent's, has the same reference. Skipping it is why a site drifts
into a different look three edits in.

## Images

Same library and the same rules as email:

```bash
mailtea assets upload --publication-id pub_123 --file ./cover.jpg --width

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.