MailAgent × OpenAI Codex

One plugin install — 21 MCP tools for disposable inboxes, OTP, magic links, threads, domains, and simulate-first QA in Codex.

Install from GitHub (Codex CLI)

codex plugin marketplace add Alex0nder/MailAgent
codex plugin install mailagent --source mailagent
codex mcp list

Set MAILAGENT_API_KEY when prompted (team key from console).

Quick install (local plugin)

git clone https://github.com/Alex0nder/MailAgent.git
cd MailAgent/examples/codex/plugin
cp .env.example .env
# edit .env — MAILAGENT_API_KEY from dashboard or issue:key:db
chmod +x scripts/run-mailagent-mcp.sh

Open examples/codex/plugin as a trusted Codex project. In Codex: codex mcp list — expect server mailagent with tools like mailagent_verify_signup.

Get an API key

Hosted: Create a team key → paste in .env
Self-host: npm run issue:key:db -- my-codex

Marketplace tarball

npm run package:codex
# → dist/mailagent-codex-plugin-0.2.5.tar.gz

Official Plugin Directory self-serve publish is coming soon; tarball is for manual share.

Recommended agent flow

mailagent_create_inbox with label + service
Submit returned address on the signup form
mailagent_wait_and_extract with subjectContains
Use otp or primaryLink to finish signup
mailagent_delete_inbox for cleanup

On timeout: mailagent_diagnose_inbox. Without real SMTP: mailagent_simulate_message.

Remote MCP (no local npx)

[mcp_servers.mailagent-remote]
url = "https://api.webmailagent.com/mcp"

[mcp_servers.mailagent-remote.http_headers]
Authorization = "Bearer YOUR_API_KEY"
Accept = "application/json, text/event-stream"

OAuth mat_ tokens: MCP OAuth.

Verify in repo

npm run verify:codex
npm run smoke:codex