Mailtea Agent Plugin

Send your first email. Design your next newsletter. Just ask.

One package that gives an AI coding agent the Mailtea MCP server and three skills for email, email design, and publication websites. It targets Agent Plugins 1.0.0 and carries a native manifest for every client that has its own format.

Get started

You need a Mailtea account. Sending also needs a verified sending domain. The hosted connection needs no API key, no Node.js install, and no code — you sign in through your browser.

Mailtea Agent Plugin

Send your first email. Design your next newsletter. Just ask.

One package that gives an AI coding agent the Mailtea MCP server and three skills for email, email design, and publication websites. It targets Agent Plugins 1.0.0 and carries a native manifest for every client that has its own format.

Get started

You need a Mailtea account. Sending also needs a verified sending domain. The hosted connection needs no API key, no Node.js install, and no code — you sign in through your browser.

npx plugins add is the universal path. The plugins CLI reads this package's plugin.json and installs it into whichever agent tools it detects — Claude Code, Cursor, Codex, Grok Build, Kimi Code, GitHub Copilot CLI, and VS Code. Use -t <target> to pick one, and npx plugins targets to see what it found.

Then open a new session, connect Mailtea through the browser sign-in prompt, choose your publication and the access you want to grant, and paste:

Help me send my first email with Mailtea. Check my setup and guide me through anything missing.

Your agent checks the publications, senders, and domain verification available to your account, and explains the next step for anything missing. You do not need to know tool names or pick a skill.

Need an account? Start with Mailtea. Need a sending domain? Domain setup.

Three skills, ready when you need them

Your agent selects the relevant skill from your request. You can also name a skill if you want to be explicit.

Copy a prompt

Send one email — replace the bracketed details with your own:

Send an email from [my verified sender] to [recipient]. Subject: [subject]. Message: [body].

Schedule a send:

Schedule this email for [date and time, including time zone]. Use [verified sender] and send only to [recipient].

Check delivery:

Check my recent Mailtea emails and explain any failed deliveries.

Create a newsletter draft:

Draft a newsletter for [publication] about [topic]. Give it a clear subject and one call to action. Do not send it yet.

Design your website:

Draft a home page for [publication] using its brand and existing content. Do not publish it yet.

What happens when you ask

• Draft means draft. Draft requests do not send email or publish a website.
• You choose who receives an email. Your agent asks for missing details and uses the sender, recipients, and content you supply or approve.
• An email ID means accepted, not delivered. Ask for delivery status to check the result. Do not repeat a send after a timeout until its status is known.
• Your permissions apply. The connection only reaches what your Mailtea account and the access you grant allow.

If you get stuck

Reconnecting per client

Package layout

The repository root is the plugin root. Every client — Agent Plugins (Cursor, VS Code, Kiro, Codex), Claude Code, Grok Build, and the Gemini CLI — loads this one directory. There is no per-client subdirectory and no second copy of the skills.

That decision follows from Agent Plugins 1.0.0 §4.1: a path a client resolves from the package must stay inside the plugin root, so a nested package cannot share skills/ with the root by symlink or relative path. Nesting would mean duplicating every skill. A single root keeps one copy, and the mirror's v<version> release tag reads plugin.json at that same root.

mailtea-agent-plugin/            # this package, and the plugin root
├── plugin.json                  # Agent Plugins 1.0.0 manifest (portable)
├── mcp.json                     # Agent Plugins MCP config (streamable-http)
├── .mcp.json                    # client-native MCP config (Codex, Grok Build)
├── skills/
│   ├── mailtea/SKILL.md         # send / schedule / manage email & newsletters
│   ├── mailtea-email-design/    # email-safe design (ops + HTML)
│   └── mailtea-site-design/     # publication website builder
├── assets/                      # icon and listing images
├── .codex-plugin/plugin.json    # Codex manifest + listing metadata
├── .claude-plugin/              # Claude Code manifest + repository marketplace
├── .cursor-plugin/              # Cursor manifest + repository marketplace
├── .grok-plugin/                # Grok Build manifest + repository marketplace
├── .agents/plugins/marketplace.json  # Codex repository marketplace
├── gemini-extension.json        # Gemini CLI extension manifest
├── server.json                  # MCP Registry entry (app.mailtea/mailtea)
├── GEMINI.md                    # Gemini CLI context file
├── scripts/check-manifests.mjs  # keeps every manifest in agreement
├── CHANGELOG.md
├── README.md
└── LICENSE

Every manifest names the same plugin at the same version with the same description, points at skills/ and the same MCP endpoint, and carries no credentials. node scripts/check-manifests.mjs enforces that; the monorepo runs it as pnpm check:agent-plugin.

What this plugin gives an agent

Which Mailtea areas this covers

1. Transactional email — send, batch, schedule, cancel, resend, delivery/open/click status
2. Newsletters / issues — draft, ops edits, preview, schedule, send, web publish
3. Email design & templates — structured blocks, lint, reusable templates + versions
4. Audience — contacts, properties, segments, topics, suppressions, CSV import
5. Automations & events — multi-step journeys, custom event ingest
6. Publication website — pages, section presets, theme, draft/publish
7. Infrastructure — sending domains, DNS verify, API keys, webhooks, analytics

It does not replace Mailtea Studio or the typed SDKs and CLI for application code. Use the plugin when an AI agent client should operate the same control plane.

Self-hosting and stdio

The hosted server at https://api.mailtea.app/mcp signs in through your client's browser flow and stores no credentials in this package. For a self-hosted API or local development, run the MCP server over stdio instead and let your client inject the token:

# Claude Code example
claude mcp add mailtea -e MAILTEA_API_TOKEN=mt_pat_xxx -- npx -y mailtea-mcp

Create a personal access token in Settings → API keys, or with POST /v1/api-keys. Never commit one: Agent Plugins forbids credentials in package files, and scripts/check-manifests.mjs fails the build if one appears in an MCP header.

Versioning

There is no npm or PyPI package — the plugin is this repository, so a release tag is how you pin one. main always holds the latest:

git clone --branch v0.3.0 --depth 1 https://github.com/mailtea-app/mailtea-agent-plugin.git

Every manifest's version matches the tag, and each release's notes come from CHANGELOG.md. Semver: a patch sharpens skill wording, a minor adds a skill or an MCP surface, a major removes or renames one.

Authoring notes

Do not add client-only hooks, commands, or marketplace metadata to the top level of plugin.json. Put those under a reverse-domain extensions key or in that client's own directory, per client extensions.

Skills here are copies of the canonical ones in the Mailtea monorepo. Edit those, then run pnpm sync:agent-plugin-skills.

Related

• Spec: agent-plugins.org · Build a plugin
• MCP package: mailtea-mcp
• Skills-only mirror: mailtea-agent-skills
• Docs: Agent Plugin

License

MIT | Windsurf | Settings → Cascade → MCP servers → add https://api.mailtea.app/mcp | | Claude.ai | Settings → Connectors → Add custom connector → https://api.mailtea.app/mcp | | ChatGPT | Settings → Connectors → Add → https://api.mailtea.app/mcp (Developer mode) |

npx plugins add is the universal path. The plugins CLI reads this package's plugin.json and installs it into whichever agent tools it detects — Claude Code, Cursor, Codex, Grok Build, Kimi Code, GitHub Copilot CLI, and VS Code. Use -t <target> to pick one, and npx plugins targets to see what it found.

Then open a new session, connect Mailtea through the browser sign-in prompt, choose your publication and the access you want to grant, and paste:

Help me send my first email with Mailtea. Check my setup and guide me through anything missing.

Your agent checks the publications, senders, and domain verification available to your account, and explains the next step for anything missing. You do not need to know tool names or pick a skill.

Need an account? Start with Mailtea. Need a sending domain? Domain setup.

Three skills, ready when you need them

Your agent selects the relevant skill from your request. You can also name a skill if you want to be explicit.

Copy a prompt

Send one email — replace the bracketed details with your own:

Send an email from [my verified sender] to [recipient]. Subject: [subject]. Message: [body].

Schedule a send:

Schedule this email for [date and time, including time zone]. Use [verified sender] and send only to [recipient].

Check delivery:

Check my recent Mailtea emails and explain any failed deliveries.

Create a newsletter draft:

Draft a newsletter for [publication] about [topic]. Give it a clear subject and one call to action. Do not send it yet.

Design your website:

Draft a home page for [publication] using its brand and existing content. Do not publish it yet.

What happens when you ask

• Draft means draft. Draft requests do not send email or publish a website.
• You choose who receives an email. Your agent asks for missing details and uses the sender, recipients, and content you supply or approve.
• An email ID means accepted, not delivered. Ask for delivery status to check the result. Do not repeat a send after a timeout until its status is known.
• Your permissions apply. The connection only reaches what your Mailtea account and the access you grant allow.

If you get stuck

Reconnecting per client

Package layout

The repository root is the plugin root. Every client — Agent Plugins (Cursor, VS Code, Kiro, Codex), Claude Code, Grok Build, and the Gemini CLI — loads this one directory. There is no per-client subdirectory and no second copy of the skills.

That decision follows from Agent Plugins 1.0.0 §4.1: a path a client resolves from the package must stay inside the plugin root, so a nested package cannot share skills/ with the root by symlink or relative path. Nesting would mean duplicating every skill. A single root keeps one copy, and the mirror's v<version> release tag reads plugin.json at that same root.

mailtea-agent-plugin/            # this package, and the plugin root
├── plugin.json                  # Agent Plugins 1.0.0 manifest (portable)
├── mcp.json                     # Agent Plugins MCP config (streamable-http)
├── .mcp.json                    # client-native MCP config (Codex, Grok Build)
├── skills/
│   ├── mailtea/SKILL.md         # send / schedule / manage email & newsletters
│   ├── mailtea-email-design/    # email-safe design (ops + HTML)
│   └── mailtea-site-design/     # publication website builder
├── assets/                      # icon and listing images
├── .codex-plugin/plugin.json    # Codex manifest + listing metadata
├── .claude-plugin/              # Claude Code manifest + repository marketplace
├── .cursor-plugin/              # Cursor manifest + repository marketplace
├── .grok-plugin/                # Grok Build manifest + repository marketplace
├── .agents/plugins/marketplace.json  # Codex repository marketplace
├── gemini-extension.json        # Gemini CLI extension manifest
├── server.json                  # MCP Registry entry (app.mailtea/mailtea)
├── GEMINI.md                    # Gemini CLI context file
├── scripts/check-manifests.mjs  # keeps every manifest in agreement
├── CHANGELOG.md
├── README.md
└── LICENSE

Every manifest names the same plugin at the same version with the same description, points at skills/ and the same MCP endpoint, and carries no credentials. node scripts/check-manifests.mjs enforces that; the monorepo runs it as pnpm check:agent-plugin.

What this plugin gives an agent

Which Mailtea areas this covers

1. Transactional email — send, batch, schedule, cancel, resend, delivery/open/click status
2. Newsletters / issues — draft, ops edits, preview, schedule, send, web publish
3. Email design & templates — structured blocks, lint, reusable templates + versions
4. Audience — contacts, properties, segments, topics, suppressions, CSV import
5. Automations & events — multi-step journeys, custom event ingest
6. Publication website — pages, section presets, theme, draft/publish
7. Infrastructure — sending domains, DNS verify, API keys, webhooks, analytics

It does not replace Mailtea Studio or the typed SDKs and CLI for application code. Use the plugin when an AI agent client should operate the same control plane.

Self-hosting and stdio

The hosted server at https://api.mailtea.app/mcp signs in through your client's browser flow and stores no credentials in this package. For a self-hosted API or local development, run the MCP server over stdio instead and let your client inject the token:

# Claude Code example
claude mcp add mailtea -e MAILTEA_API_TOKEN=mt_pat_xxx -- npx -y mailtea-mcp

Create a personal access token in Settings → API keys, or with POST /v1/api-keys. Never commit one: Agent Plugins forbids credentials in package files, and scripts/check-manifests.mjs fails the build if one appears in an MCP header.

Versioning

There is no npm or PyPI package — the plugin is this repository, so a release tag is how you pin one. main always holds the latest:

git clone --branch v0.3.0 --depth 1 https://github.com/mailtea-app/mailtea-agent-plugin.git

Every manifest's version matches the tag, and each release's notes come from CHANGELOG.md. Semver: a patch sharpens skill wording, a minor adds a skill or an MCP surface, a major removes or renames one.

Authoring notes

Do not add client-only hooks, commands, or marketplace metadata to the top level of plugin.json. Put those under a reverse-domain extensions key or in that client's own directory, per client extensions.

Skills here are copies of the canonical ones in the Mailtea monorepo. Edit those, then run pnpm sync:agent-plugin-skills.

Related

• Spec: agent-plugins.org · Build a plugin
• MCP package: mailtea-mcp
• Skills-only mirror: mailtea-agent-skills
• Docs: Agent Plugin

License

MIT