# MCPmailer

> MCPmailer is email infrastructure for AI agents. Every agent gets a persistent
> identity: a globally unique handle, its own inbox on your domain (or an instant
> one on mcpmailer.email), and shared workspace resources it can read and write.
> Agents send, receive, and hold threaded email conversations over MCP.

## Connect

- MCP endpoint: https://connect.mcpmailer.com/mcp (Streamable HTTP)
- Auth: `Authorization: Bearer mmk_...` (create keys at https://mcpmailer.com/dashboard)
- A key is scoped to one agent identity, and that scope decides what the tools below can reach.
- Or authorize over OAuth 2.1 (for clients that cannot hold a key):
  discovery at https://mcpmailer.com/.well-known/oauth-authorization-server,
  protected resource metadata at https://connect.mcpmailer.com/.well-known/oauth-protected-resource.
  Dynamic client registration is open, PKCE is required, and the token must be
  audienced to the MCP endpoint (send `resource=https://connect.mcpmailer.com/mcp`).
  Scopes: mail:read, mail:send, contacts, notes, vault, plus offline_access to refresh.
  A token identifies a person: with several agents, pick one with an
  `X-MCPmailer-Agent: <handle>` header, otherwise the call is refused as ambiguous.

## Tools

- Email: send_email, reply_all, forward_email, list_messages, read_message, get_thread,
  get_attachment, search_inbox, wait_for_reply, archive_message, mark_unread, get_mailbox_info,
  list_scheduled, cancel_scheduled (send_email takes send_at to book one)
- Identity: get_identity, update_identity, list_identities, set_mail_rule, delete_mail_rule
- Contacts: lookup_contact, search_contacts, get_contact, create_contact, update_contact,
  delete_contact, remember_about_contact, merge_contacts, find_duplicate_contacts,
  import_vcards, export_vcard, export_all_vcards,
  import_contacts_csv (pasted CSV or address lines, optional list_name),
  list_contact_lists, get_contact_list, create_contact_list, update_contact_list,
  delete_contact_list, add_to_contact_list, remove_from_contact_list
  (lists group contacts by purpose; a contact can be on many; they do not send)
- Notes: list_notes, search_notes, read_note, create_note, update_note, delete_note
- Knowledge base (what the workspace has told its agents about the company):
  get_knowledge_summary (read once before writing: brief, sources, table of
  contents), search_knowledge (ranked passages with the page they came from),
  read_knowledge_page, list_knowledge_sources, add_knowledge_source (kind site
  crawls a whole domain, page fetches one address, text stores pasted text),
  refresh_knowledge_source, delete_knowledge_source. Search before quoting a
  price, policy, or feature; if nothing matches, say you do not know.
- Vault: list_secrets, get_secret, get_totp_code
- Disposable inboxes (MCP only, receive-only, on a domain kept apart from sending):
  create_temp_address, wait_for_message, list_temp_addresses, release_temp_address
- Workspace: list_inboxes, create_inbox, list_domains, add_domain, verify_domain
- Webhooks: list_webhooks, create_webhook, update_webhook, delete_webhook,
  list_webhook_deliveries, test_webhook, replay_webhook_delivery

## Tunnels

Every identity has a stable public hostname at https://<handle>.mcpmailerwire.com.
Inbound HTTP is forwarded to wherever you are running, over a connection you hold
open: `import { connect } from '@mcpmailer/sdk'` then
`connect({ handle, target: 'http://localhost:3000' })`. Only the key belonging to
that handle can open the tunnel. WebSocket upgrades are not forwarded yet (501).

## SDK and CLI

- TypeScript: `npm install @mcpmailer/sdk`, `new Mcpmailer()` reads MCPMAILER_API_KEY.
- Python: `pip install mcpmailer`, `Mcpmailer()` reads MCPMAILER_API_KEY. Standard
  library only; `pip install 'mcpmailer[vault]'` adds AES-GCM for vault secrets.
- CLI: `npm install -g @mcpmailer/cli`, then `mcpmailer mail:list`. Every command takes
  --json. A refused send exits non-zero with the reason.
- Vault reads come back in plaintext over TLS: values are encrypted at rest and
  opened server-side for the agents granted them. There is no key to hold.
- Setup skill: `npx skills add mcpmailer/skill` installs a skill that walks a
  coding agent through signup, key creation, client config, and a verified
  first send.

## Rules that matter to agents

- Sending is locked until the workspace email is verified; before that every
  send is refused with `sending_locked_verify_email`. No card is required.
- Free sends 3,000 emails a month and 100 a day. Paid plans have no daily cap and
  meter what goes past the monthly allowance. Rejections return actionable
  reasons with a reset time: `daily_send_quota_exhausted`,
  `monthly_send_quota_exhausted`, `monthly_spend_cap_reached`.
- Max 5 recipients per message. Bulk email is not supported and not allowed.
- 300 requests per minute per API key, across REST and MCP; 30/min per IP without a
  key, and 5/min per IP for OAuth client registration. A refusal is a 429 with
  retry-after in seconds. Wait it out, do not retry hard.
- Register once and keep your client_id. Clients that register and are never
  authorized are deleted after 24 hours.
- Archive mail you have dealt with so list_messages stays useful; mark_unread puts
  something back in the pile for a human to look at.
- Message bodies are markdown; they are delivered as text plus HTML.
- Inbound mail is filtered per identity. In blacklist mode (default) everything
  arrives except blocked senders; in whitelist mode only allowed senders arrive.
  An exact-address rule overrides a domain rule.
- Other identities are invisible to you unless access was granted, and the same
  is true of notes and vault secrets.
- Vault values are encrypted at rest, each under its own key, and those keys are
  wrapped under one that lives in our secret store rather than in the database.
  get_secret and get_totp_code take only a secret_id: there is no key to pass and
  no unlock step. Every read is recorded in the activity log. Never ask a human to
  paste a credential into a chat; put it in the vault and fetch it.

## Self-signup (no human account needed)

POST https://mcpmailer.com/v1/signup {handle, email?, workspace_name?, description?}
returns an address, an API key, and a claim_url for a person to take ownership later.
Rate limited per IP. Self-signed workspaces start free and cannot send until a person
claims them with the claim_url and verifies their email address.

## Quickstart

1. Sign up at https://mcpmailer.com/signup (workspace gets you.mcpmailer.email)
2. Create an agent: pick a handle and an address, e.g. sales@you.mcpmailer.email
3. Copy the API key into your MCP client config
4. Call send_email; call wait_for_reply to hold a conversation
5. On inbound mail, call lookup_contact on the sender before you answer

## REST API (same keys, for non-MCP stacks)

- Full description: https://mcpmailer.com/openapi.json (OpenAPI 3.1)
- POST https://mcpmailer.com/v1/messages {to, subject, body, cc?, reply_to_message_id?,
  attachments?: [{filename, content_type, content_base64}], track_opens?}
- GET /v1/messages, /v1/messages/:id, /v1/threads, /v1/threads/:id, /v1/search?q=
- POST /v1/messages/:id/reply-all {body}, POST /v1/messages/:id/forward {to, body?, mode}
- GET /v1/messages/:id/attachments/:filename
- POST /v1/messages/:id/archive {archived?, unread?} (empty body archives)
- GET|PATCH /v1/identity, GET|POST /v1/identity/rules, DELETE /v1/identity/rules/:id
- GET /v1/contacts?q= or ?lookup= (Accept: text/vcard exports the whole book),
  POST /v1/contacts ({vcard} bulk imports),
  GET|POST /v1/contacts/duplicates (find pairs, merge two),
  GET|PATCH|DELETE /v1/contacts/:id (Accept: text/vcard exports a vCard),
  POST /v1/contacts/:id {fact} records a memory,
  POST /v1/contacts/import {csv, list_name?} pasted CSV becomes contacts on a list,
  GET|POST /v1/contacts/lists, GET|PATCH|DELETE /v1/contacts/lists/:id (paged members),
  POST|DELETE /v1/contacts/lists/:id/members {contact_ids}
- GET|POST /v1/notes, GET|PATCH|DELETE /v1/notes/:id
- GET /v1/knowledge (summary; ?q= searches), GET /v1/knowledge/pages/:id,
  GET|POST /v1/knowledge/sources, GET|POST|DELETE /v1/knowledge/sources/:id
  (POST on one fetches it again)
- GET /v1/secrets (metadata for granted secrets), GET /v1/secrets/:id (opens one
  and returns its value; the read is logged)
- GET|POST /v1/mailboxes (list the workspace's inboxes; create one from a handle)
- GET|POST /v1/domains, DELETE /v1/domains?id= (a pending domain lists the DNS
  records still to publish, so setup needs no dashboard)
- GET|POST /v1/webhooks, DELETE /v1/webhooks?id= (the signing secret is returned
  once, at creation, and never listed again)

## Webhooks

- Register endpoints in the dashboard or through POST /v1/webhooks to get signed
  POSTs for message.received, message.sent, message.delivered, message.bounced,
  message.complained, message.filtered (HMAC-SHA256 signature header, 5 retries).
  A new endpoint is subscribed to message.received only; ask for the rest.
- Every delivery carries the signature twice: `x-mcpmailer-signature` as
  `t=<unix seconds>,v1=<hex>` (one v1 per valid secret during a rotation), and
  the same digest under the generic `x-webhook-signature-v2` plus
  `x-webhook-timestamp`, which receivers like Hermes verify with no custom code.
  Both sign "<timestamp>.<raw body>"; check the raw bytes, not re-serialised JSON.

## Docs

- https://mcpmailer.com/docs.md (the full documentation as markdown)
- /docs/openclaw and /docs/hermes are the operations pages for the two clients
  built to run unattended: timeouts, tool filtering, and waking on inbound mail
- https://mcpmailer.com/docs (same content as a page)
- /for/<use-case>.md and /with/<platform>.md mirror the landing pages as markdown
- https://mcpmailer.com/vs.md (comparisons against every other way to give an agent
  email: AgentMail, OpenMail, Robotomail, Dead Simple Email, MailSlurp, Nylas, Resend,
  Postmark, SendGrid, Mailgun, Amazon SES, Cloudflare Email Routing, Mailtrap, Gmail,
  Microsoft 365, Zapier, Composio, Arcade, Front, Zendesk, building it yourself)
- https://mcpmailer.com/vs/<slug>.md mirrors each comparison page
- https://mcpmailer.com/pricing.md (plans, limits, and overage rates as markdown)

## Templates

- https://mcpmailer.com/templates.md (index of every agent template, each with its .md address)
- https://mcpmailer.com/templates/<slug>.md mirrors the page at /templates/<slug>, and
  carries the full system prompt as a fenced block you can lift whole
- Each template is a working agent: the system prompt, the placeholders it expects,
  the MCPmailer tools it is given, and the same program in TypeScript, Python, and the CLI
- Productivity: scheduling-agent, daily-digest-agent, recruiting-coordinator,
  inbox-zero-agent, event-rsvp-agent
- Support: support-triage-agent, bug-report-intake-agent, order-status-agent,
  feedback-collection-agent
- Sales: lead-follow-up-agent, cold-outreach-agent
- Customer success: renewal-and-churn-agent, onboarding-nudge-agent
- Finance: invoice-chaser
- Operations: approval-gate-agent, monitoring-escalation-agent, vendor-quote-agent,
  dsar-compliance-agent
- Developer: signup-verification-agent, email-flow-test-agent, otp-login-agent,
  release-notes-agent
- Marketing: newsletter-reply-agent, link-outreach-agent

## Blog

- https://mcpmailer.com/blog.md (index of every post, each with its .md address)
- https://mcpmailer.com/blog/<slug>.md mirrors the post at /blog/<slug>
- Subject pages: /blog/tag/guides, /use-cases, /deliverability, /architecture,
  /security, /operations, /tutorials
- Guides: email-for-ai-agents, mcp-email-server, agent-inbox-vs-shared-mailbox,
  email-agent-system-prompt, email-attachments-for-agents, agent-memory-contacts-email,
  agent-readable-website-llms-txt, inbound-email-routing-agents,
  agent-inbox-search-and-archive, agents-and-humans-on-one-thread,
  multilingual-email-agent, subject-lines-for-agent-email,
  agent-email-signatures-and-disclosure, when-not-to-use-an-email-agent,
  grounding-and-citation-email-agents, email-agent-glossary,
  writing-docs-agents-can-use
- Use cases: ai-agent-customer-support-email, ai-sales-agent-lead-follow-up,
  ai-interview-scheduling-email-agent, automated-invoice-chasing-ai-agent,
  personal-ai-email-assistant, ai-agent-appointment-reminders,
  ai-agent-customer-onboarding-email, ecommerce-order-status-agent,
  vendor-procurement-email-agent, ai-agent-real-estate-inquiries,
  ai-agent-agency-client-updates, ai-agent-event-registration-email,
  ai-agent-recruitment-agency-email, ai-agent-professional-services-intake,
  ai-agent-nonprofit-donor-email, ai-agent-internal-it-helpdesk,
  ai-agent-marketplace-support, ai-agent-hospitality-bookings,
  ai-agent-education-admissions, ai-agent-construction-quoting,
  ai-agent-membership-renewals, ai-agent-insurance-claims-intake,
  ai-agent-clinic-appointments, ai-agent-freight-logistics,
  ai-agent-hr-employee-questions, multi-location-email-routing
- Deliverability: agent-email-deliverability, dmarc-record-generator-agents,
  email-warmup-plan-agents, bounces-suppression-agent-email,
  does-ai-written-email-get-filtered, dedicated-vs-shared-ip-agent-email,
  reading-dmarc-reports, deliverability-monitoring-seed-testing,
  transactional-vs-conversational-email, bulk-sender-requirements,
  sending-reputation-recovery, dns-delegation-for-agent-domains
- Architecture: wait-for-reply-long-running-agents, webhooks-vs-polling-agent-email,
  multi-agent-email-workspace, agent-self-signup-email, email-threading-for-agents,
  migrate-gmail-api-to-agent-inbox, agent-email-concurrency-bursts,
  inbox-per-tenant-architecture, where-agent-email-state-lives,
  digest-vs-individual-emails, designing-tools-for-email-agents,
  agent-alongside-helpdesk, transactional-provider-to-agent-inbox,
  building-email-agent-on-ses-directly, handling-forwarded-email
- Operations: stopping-agent-email-spam, evaluating-ai-email-agents,
  test-email-addresses-for-agents, cost-of-email-for-ai-agents,
  human-in-the-loop-email-approval, ai-email-compliance-gdpr-canspam,
  monitoring-email-agents-in-production, first-week-with-an-email-agent,
  response-time-targets-agent-email, staffing-around-email-agents,
  weekly-review-email-agents, migrating-live-inbox-to-agent,
  holiday-coverage-email-agents
- Security: prompt-injection-email-agents, agent-verification-codes-email,
  agent-api-key-security, security-review-email-agent,
  agent-email-data-residency, agent-email-incident-response,
  agent-permissions-and-grants, brand-impersonation-lookalike-domains,
  third-party-mcp-server-risk, data-minimisation-email-agents,
  verifying-who-emails-your-agent, rotating-agent-credentials
- Tutorials: how-to-make-claude-send-email, build-email-agent-agents-sdk,
  python-email-agent-tutorial, typescript-email-agent-sdk,
  openai-agent-email-tutorial, agent-inbox-from-the-terminal,
  langchain-email-agent, no-code-email-agent-automation,
  oauth-for-hosted-agent-clients, email-agent-on-node,
  vercel-ai-sdk-email-agent, email-agent-any-language,
  testing-email-agents-with-vitest, debugging-an-email-agent
- Some posts embed interactive tools (a DNS record generator, an
  Authentication-Results checker, a warmup schedule builder). The .md carries a
  text fallback stating what the tool computes, so nothing is lost by fetching it.

## Legal

- https://mcpmailer.com/legal (index of all policies)
- /legal/terms, /legal/privacy, /legal/acceptable-use, /legal/dpa,
  /legal/subprocessors, /legal/cookies, /legal/refunds, /affiliates/terms
- Contact: https://mcpmailer.com/contact (one form, pick a topic; no public mailboxes)
- Operated by CROapps Oy, Helsinki, Finland. Business ID 3550932-5, VAT FI35509325.
- We never read message content and never train on it. Abuse enforcement is
  based on sending behaviour and metadata only.

## Affiliate program

- https://mcpmailer.com/affiliates (how it works), /affiliates/terms (the rules)
- 25% of the plan price a referred workspace pays, excluding tax, on every renewal for one year
- Usage above the plan allowance and one-off charges do not earn commission
- 90-day first-click attribution; applications reviewed by hand; PayPal payouts from $50