# MailFlat

> Permanent email inboxes for AI agents, developers, and everyday use — one API call opens a real inbox, and OTP codes and magic links come back as structured data.

MailFlat is an email infrastructure service built by Yentar Labs LLC that provides permanent, on-demand inboxes for AI agents, test suites, and everyday privacy use. It ships a web inbox, a REST API, an MCP server, and official SDKs for Python, TypeScript/JavaScript, Java, LangChain, and the Vercel AI SDK — all backed by the same inbox engine with real SMTP delivery, SPF, DKIM, and DMARC authentication.

## What It Is

MailFlat sits in the intersection of disposable email, email testing infrastructure, and AI agent tooling. Unlike a traditional disposable-email service where the address disappears with the messages, MailFlat keeps addresses permanent while auto-purging message contents on a configurable timer (2 hours by default, up to 30 days on paid plans). The core value proposition is that a test suite, a CI pipeline, or an AI agent can call `create_inbox()`, receive a real deliverable address, read back the OTP or magic link the target service sent, and move on — with no mock server, no shared mailbox state, and no cleanup logic needed.

## Four Surfaces, One Engine

The homepage describes four distinct use modes powered by the same backend:

- **Web inbox** — A browser-based inbox for everyday privacy use. Users paste the address wherever a site demands an email, let messages auto-clear after two hours, and keep the address indefinitely.
- **Developer API** — A REST API (`/api/v1`) with SDKs for Python, JavaScript/TypeScript, Java, and more. Designed for per-test inbox isolation in Playwright, Cypress, Selenium, pytest, and GitHub Actions workflows.
- **AI agent tooling** — An MCP server (`mailflat-mcp`, installable via `uvx mailflat-mcp`) plus a tool spec compatible with GPT, Claude, and LangChain. Agents register MailFlat as a tool, spin up inboxes on demand, and call `wait_for_otp()` to retrieve verification codes without any bot-detection friction. The terms of service explicitly permit automation.
- **Custom domains (BYOD)** — Users verify a domain once via DNS records, then spin up addresses like `billing@acme.com` on the fly. Free accounts get one custom domain; Pro plans support up to 250.

## Architecture and Delivery Model

MailFlat operates real mailboxes on authenticated domains rather than a sandbox or capture proxy. The GitHub README notes that the service itself is closed-source, while the SDKs are MIT-licensed. Inboxes are created in under 80ms according to the homepage. End-to-end encryption is an opt-in feature for personal inboxes: when enabled, messages are sealed on receipt with a key generated locally in the browser, and the server stores only ciphertext. Agent and CI inboxes deliberately remain readable so the API can extract one-time codes and links. Auto-purge keeps agent context windows clean by ensuring old messages do not accumulate.

## SDK and Integration Coverage

The official SDK repository (`github.com/MailFlat/mailflat-sdks`) covers:

- **Python** — `pip install mailflat`, with an optional `mailflat[langchain]` extra
- **JavaScript / TypeScript** — `npm i @mailflat/sdk`
- **Vercel AI SDK** — `npm i @mailflat/ai-sdk`
- **MCP server** — `uvx mailflat-mcp` for Claude Desktop, Cursor, and any MCP-compatible host
- **Java** — available via JitPack, with Maven Central (`net.mailflat`) planned as the next distribution target
- **LangChain** — included in the Python package as an optional extra

The docs list 9 language guides and 13 test-framework and CI integration guides, including Playwright, Cypress, Selenium, and pytest.

## Update: SDK v0.7.0 (September 2026)

The SDK repository reached v0.7.0 on September 29, 2026, with the Java client migrating to the official `MailFlat` GitHub organization (coordinate `com.github.MailFlat:mailflat-sdks`) starting at v0.4.4. The README notes a planned move to Maven Central under `net.mailflat` to remove the owner-coupling dependency. The repository was created in August 2026, indicating MailFlat is a recently launched product still in early growth.

## Features
- Permanent email addresses with auto-purging messages
- On-demand inbox creation via API in under 80ms
- Built-in OTP extraction (wait_for_otp)
- Magic link parsing for agent workflows
- MCP server for Claude, Cursor, and MCP-compatible hosts
- Tool spec for GPT, Claude, and LangChain agents
- End-to-end encryption (opt-in, per-inbox)
- Custom domain support (BYOD) with SPF, DKIM, DMARC
- Real SMTP delivery on authenticated domains
- SDKs for Python, TypeScript/JavaScript, Java, LangChain, Vercel AI SDK
- Per-test inbox isolation for CI pipelines
- Configurable message retention (2 hours to 30 days)
- No automation clauses in ToS
- Webhooks on paid plans
- Auto-purge keeps agent context windows clean

## Integrations
Playwright, Cypress, Selenium, pytest, GitHub Actions, GPT (OpenAI), Claude (Anthropic), LangChain, Vercel AI SDK, OpenAI Agents SDK, Cursor, Claude Desktop, Java / JitPack, MCP (Model Context Protocol)

## Platforms
WEB, API, CLI, DEVELOPER_SDK

## Pricing
Freemium — Free tier available with paid upgrades

## Version
v0.7.0

## Links
- Website: https://mailflat.net
- Documentation: https://mailflat.net/docs
- Repository: https://github.com/MailFlat/mailflat-sdks
- EveryDev.ai: https://www.everydev.ai/tools/mailflat