Gateweave Mail

Gateweave Mail is part of Gateweave, the family of open-source business tools that run on Cloudflare, next to Gateweave Track, Gateweave ID and Gateweave Agents.

Status: early development. Mail receives and keeps mail, and sends it, formatted and with files, from people and agents. What exists is sign-in, workspaces, a directory of domains and addresses, and mailboxes whose messages the people given them read and answer. Expect breaking changes until 1.0; see CHANGELOG.md.

What works today

• Accounts. Sign-up, sign-in, password reset (with email set up), sign-out, deleting your account and an account page, with limits on password tries and on account changes.
• Sign-in through a provider. “Continue with Gateweave”, or any OpenID Connect provider you configure, and optionally GitHub. Each is off until configured.
• Workspaces. Create one, invite people by link or email, and give them roles (owner, admin or member).
• Domains, mailboxes and addresses. Prove a domain with a DNS record, make mailboxes, and give them addresses, for good or for a set number of days. Owners and admins read every mailbox and choose who else reads each one: everyone in the workspace, or the people they pick.
• Receiving mail. The Worker’s email() handler looks up each message’s address and refuses one that doesn’t exist. Mail for one that does is kept in its mailbox, once even when it arrives twice, up to 1 GiB per mailbox, and encrypted in R2 when the server has a SECRETS_KEY.
• Reading mail. Whoever may read a mailbox sees its threads, newest news first, and reads their messages, with each attachment and the original to download. HTML mail shows in a sandbox that runs nothing and loads remote images only when asked, or by themselves for a sender the reader allowed by its proved domain. Replies join the thread of the message they answer, or of other replies to it, when their subject matches. A sender’s domain shows as proved only when the message passed DMARC for it, or came from a mailbox on the same deployment. Owners and admins can delete a message.
• Search. Find a mailbox’s threads by the words in their messages: subject, sender, text and attachment names.
• Replying and writing. Whoever reads a mailbox replies to its mail and writes new mail from its addresses, through Cloudflare Email Service. Bold, italic, links, lists and quotes are marked in the text, with buttons and a preview, and a message that uses them goes as HTML too; files are attached, dropped or pasted. The copy shows in its thread at once, with who wrote it and whether it went; one that wasn’t sent can be sent again or discarded, and one that may have gone is never sent twice by itself.
• Mail between your own mailboxes stays in. A message whose every recipient is an address on the same deployment goes straight to their mailboxes, with no send and no round trip through DNS, and its sender’s domain shows as proved there.
• Resend for domains elsewhere. A domain whose DNS isn’t on your Cloudflare account can send through Resend instead, with the workspace’s own key, which Mail keeps encrypted and never shows again.
• Agents. An admin makes an agent for an AI agent and gives it a key. It reads, over MCP or through the API, only the mailboxes it is given; opening a mailbox to everyone doesn’t open it to agents. Mail’s MCP server, at /mcp, has tools that wait for mail to come and hand over the code in a sign-up or sign-in message without the rest of its text. The same operations are a REST API at /api/v1, described by an OpenAPI document at /api/v1/openapi.json. A mailbox can let an agent send too, in text or HTML and with files. Mail to the addresses and domains its settings name goes on its own; the rest waits for someone who reads the mailbox to approve or reject it. Each agent has a daily limit of its own. An agent can also make addresses for itself, such as one for each sign-up, on the domains an admin gives it, as many and for as long as the admin allows. Each one ends. One button pauses an agent: its keys do nothing until it is resumed, and what it wrote that waits to be tried again waits for a person instead. Each agent has a page of its own that shows what it wrote, what of that waits for approval, and what came to the addresses it made, and a log of what it did with its keys, each message it read included, and what people changed about it, kept for 90 days. An agent can say what a message it sends is for, a link to the run, issue or pull request behind it, which people see beside the message and webhooks carry, and which never goes into the mail. The workspace’s home lists its agents first, for owners and admins: each one’s addresses, what it sent, held and read in the last day, and the last thing it did.
• Webhooks. Mail posts each message a mailbox receives to a URL of yours, such as an agent’s trigger, signed per Standard Webhooks, with who sent it and what it is about but not what it says. It tells of mail you send too: held for approval, rejected, sent, and delivered, bounced or marked as spam at each recipient. It retries for about a day while the receiver fails. An agent can make a few webhooks of its own with its key, which hear only of the mailboxes it may read, not of what it did itself, and last as long as the key.

Connect an agent

An admin makes an agent under Settings → Agents in a workspace, and copies its key, which is shown once. Then:

• Claude Code: Mail’s plugin adds its MCP server and a skill that says how to use it well: codes rather than whole messages, mail that waits for approval, addresses of its own, and mail as data, never instructions. Install it with your Mail’s MCP address:

  claude plugin install gateweave-mail --marketplace gateweavehq/mail --config mcp_url=https://mail.example.com/mcp

  Then run /plugin configure gateweave-mail@gateweave-mail in Claude Code and paste the key. Claude Code keeps it with its own sign-in (in the macOS Keychain, or in .credentials.json in its folder elsewhere), not in its settings or the project. If your Claude Code doesn’t know --marketplace, run claude plugin marketplace add gateweavehq/mail first, then claude plugin install gateweave-mail@gateweave-mail --config mcp_url=…. If you connected an agent with claude mcp add before, remove that with claude mcp remove gateweave-mail, as it kept the key in Claude Code’s settings. claude plugin update gateweave-mail@gateweave-mail brings the skill up to date.

• A repository’s coding agents: in Gateweave Agents, add the ready-made Gateweave Mail setup under Setups, give it your Mail’s MCP address, and apply it to the repository. Its pull request writes the skill and the MCP settings for Claude Code, Codex, Gemini CLI, Cursor and GitHub Copilot. They read the key from the GATEWEAVE_MAIL_KEY environment variable, so it is never in the repository.

• Any other agent: point its MCP client at https://mail.example.com/mcp with the header Authorization: Bearer <key>, and give it the skill, plugins/gateweave-mail/skills/mail/SKILL.md, which is plain Markdown.

• Code of your own: @gateweave/mail is a TypeScript client with a method for each route, typed from the API’s document, a check of a webhook’s signature, and a command line, gateweave-mail, that waits for a sign-in code or sends a message from a script or a CI job. It isn’t on npm yet: its README says how to install a release from pkg.gateweave.com. Or call the REST API at https://mail.example.com/api/v1 with the same header; /api/v1/openapi.json describes it.

What it is planned to become

None of this exists yet; it is the direction, and it may change.

• Agents that act on mail as well as read and send it, such as filing or labelling it.
• Images in the composer’s HTML, forwarding, and replying to all.
• Aliases that point at a mailbox.
• Transactional sending and templates, through Cloudflare Email Service.

How it is built, and what isn’t yet, is in docs/architecture.md.

Tech stack

TanStack Start · React 19 · Tailwind CSS 4 · Better Auth · Drizzle ORM · Cloudflare Workers, Durable Objects, D1 and R2 · TypeScript 7 · Vitest · Biome

Getting started

Requirements: Node.js 24 (22+ works) and pnpm 12.

pnpm install
pnpm doctor      # checks your toolchain and setup, and explains how to fix anything missing
pnpm dev:setup   # creates .dev.vars with a random secret, migrates the local database
pnpm dev         # http://localhost:4750

Sign up with any email and password, then create a workspace. To enable “Sign in with GitHub” or a provider such as Gateweave ID, uncomment and fill in its keys in .dev.vars.

Scripts

Command	What it does
pnpm dev	Run the app locally with Workers, D1 and Durable Objects
pnpm doctor	Check the local toolchain and setup
pnpm check	Lint and format check (Biome)
pnpm format	Apply formatting and safe lint fixes
pnpm typecheck	Type-check the app
pnpm test	Run the test suites
pnpm test:e2e	Build, then run the browser tests (Playwright)
pnpm build	Production build
pnpm verify	Everything CI runs: check, typecheck, test and build

Self-hosting

The button copies Mail to your GitHub or GitLab account, creates the database, and deploys it to your Cloudflare account; every push to your copy deploys again. From the command line:

pnpm wrangler login
pnpm run deploy    # builds, applies D1 migrations, deploys

You need a Cloudflare account with the Workers Paid plan: a password sign-in takes more CPU than the Free plan gives a request, and Email Sending needs Paid as well. When mail ships it will also need a domain of its own, or that domain’s catch-all. docs/self-hosting.md covers both ways, your own domain, sign-in providers, email and updating.

Project structure

apps/web               The Worker: UI, auth, the email() handler, D1 schema
plugins/gateweave-mail The Claude Code plugin: Mail's MCP server and the skill for agents
.claude-plugin/        The marketplace that offers the plugin
docs/                  Architecture and self-hosting
scripts/               Repository tooling
wrangler.jsonc         The Worker's Cloudflare configuration, at the root for the Deploy button

Read docs/architecture.md for how it is built, and CHANGELOG.md for what each release changed.

Contributing

Contributions are welcome. See CONTRIBUTING.md and our Code of Conduct. If you work with an AI coding agent, point it at AGENTS.md. Report security issues privately, as described in SECURITY.md.

License

Copyright © 2026 Yiğit Tanrıverdi.

Gateweave Mail is licensed under the GNU Affero General Public License v3.0. You can self-host, use and modify Mail freely. If you run a modified version as a network service, you must make your changes available to its users under the same license.

Contributions are accepted under the Contributor License Agreement.