English Français العربية

MailFlat

Official registry Developer tools

Real email inboxes for AI agents: open an address, read the one-time code, send mail.

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package mailflat-mcp
Claude Code 
claude mcp add mailflat -e 'MAILFLAT_API_KEY=<your mailflat_api_key>' -e 'MAILFLAT_API_URL=<MAILFLAT_API_URL>' -- uvx mailflat-mcp==0.9.2
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "mailflat": {
            "command": "uvx",
            "args": [
                "mailflat-mcp==0.9.2"
            ],
            "env": {
                "MAILFLAT_API_KEY": "<your mailflat_api_key>",
                "MAILFLAT_API_URL": "<MAILFLAT_API_URL>"
            }
        }
    }
}

Environment variables

  • MAILFLAT_API_KEY required secret MailFlat API key. Create one in the dashboard under Agents.
  • MAILFLAT_API_URL Override the API base URL. Defaults to https://mailflat.net.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. MailFlat SDKs
  2. Packages
  3. Java / Selenium (JitPack)
  4. Quick examples
  5. License

MailFlat SDKs

Official client libraries for MailFlat: email inboxes your code owns, with one-line OTP retrieval. Built for test suites (Selenium, pytest, Playwright) and AI agents.

Addresses are permanent, so a suite does not need a fresh one per run. Only the messages expire, on a retention window you choose.

This repo holds only the open-source SDKs. The MailFlat service itself is closed-source.

Packages

PackageForInstall
mailflatPythonpip install mailflat
@mailflat/sdkJavaScript / TypeScriptnpm i @mailflat/sdk
mailflat-mcpAI assistants (Claude, Cursor) — MCPuvx mailflat-mcp
@mailflat/ai-sdkVercel AI SDK agentsnpm i @mailflat/ai-sdk
mailflat.langchainLangChain agentspip install "mailflat[langchain]"
mailflat-sdk (Java)Java / Seleniumvia JitPack — see below

Each client is a thin, typed wrapper over the same /api/v1 Agent API, so they behave identically. Authenticate with your account key (mf_live_…) from the dashboard (Agents → API keys).

Java / Selenium (JitPack)

JitPack derives the groupId from the GitHub owner. This repo moved to the official MailFlat account in August 2026, so releases from v0.4.4 on publish as com.github.MailFlat:mailflat-sdks. Earlier versions still resolve under the old coordinate com.github.onderyentar21:mailflat-sdks; the old repo stays up for them. The client is moving to Maven Central (net.mailflat) next, which ends the owner coupling.

<repositories>
  <repository><id>jitpack.io</id><url>https://jitpack.io</url></repository>
</repositories>

<dependency>
  <groupId>com.github.MailFlat</groupId>
  <artifactId>mailflat-sdks</artifactId>
  <version>v0.8.1</version>
</dependency>
MailFlat mf = new MailFlat("mf_live_…");
Inbox inbox = mf.create("signup");
driver.findElement(By.id("email")).sendKeys(inbox.address());
String otp = inbox.waitForOtp(30);          // polls until the code arrives
driver.findElement(By.id("code")).sendKeys(otp);

Quick examples

Python

from mailflat import MailFlat
mf = MailFlat(api_key="mf_live_…")
inbox = mf.create(label="signup")
otp = inbox.wait_for_otp(timeout=30)

JavaScript / TypeScript

import { MailFlat } from "@mailflat/sdk";
const mf = new MailFlat({ apiKey: process.env.MAILFLAT_API_KEY });
const inbox = await mf.create({ label: "signup" });
const otp = await inbox.waitForOtp({ timeout: 30000 });

License

MIT. The full text is in LICENSE at the repository root; each package directory carries an identical copy.

Frequently asked questions

What is MailFlat?

Real email inboxes for AI agents: open an address, read the one-time code, send mail.

How do I install MailFlat?

It runs on your machine. In Claude Code: claude mcp add mailflat -e 'MAILFLAT_API_KEY=<your mailflat_api_key>' -e 'MAILFLAT_API_URL=<MAILFLAT_API_URL>' -- uvx mailflat-mcp==0.9.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does MailFlat need an API key?

Yes. It expects MAILFLAT_API_KEY, which you set in its configuration.

Is MailFlat open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains MailFlat?

It is published by MailFlat. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.