Repository avatar
AI Tools
v1.0.0
active

flowmails-mcp

io.github.wms-why/flowmails-mcp

Hosted MCP server for custom-domain email: send, receive and wait for mail on your domain.

Documentation

Flowmails MCP

The hosted Model Context Protocol server for Flowmails — a custom-domain email platform built for AI agents.

Point any MCP client at https://sdk.flowmails.net/mcp with a Flowmails bearer token, and the agent gets a mailbox on your own domain: send mail, read the inbox, search history, and wait for an inbound message instead of polling.

  • Transport: MCP Streamable HTTP, JSON-RPC 2.0, protocol revision 2025-06-18
  • Auth: Authorization: Bearer <flowmails-api-key> (an SDK key fm_… or an agent credential agc_…)
  • Tools: 12 (ten of them can change mailbox state; every call is scope-checked first)
  • Run it: hosted — nothing to install, no server to operate
  • Pricing: the platform's — Base is free, Pro $9.9/mo, Enterprise $39.9/mo. Your email provider bills you directly; Flowmails charges no per-email markup.

Why it exists

Most "email MCP servers" wrap an inbox API. This one is built around the hard part of agent workflows: waiting.

wait_for_email opens a durable wait on an address and a subject. The platform owns that state, so the wait survives the edge, and the agent is handed the message when it lands — it does not spin on an inbox polling loop. That is the difference between an agent that can run a sign-up flow unattended and one that has to be babysat.

Sending is the same contract as the REST API and the official SDK: one key, bound to one domain, with an idempotency key and an audit trail behind every send.

Install

Claude Code / Claude Desktop

claude mcp add --transport http flowmails https://sdk.flowmails.net/mcp \
  --header "Authorization: Bearer fm_..."

Cursor / VS Code / Codex / any MCP client

{
  "mcpServers": {
    "flowmails": {
      "url": "https://sdk.flowmails.net/mcp",
      "headers": {
        "Authorization": "Bearer fm_..."
      }
    }
  }
}

Any client, raw JSON-RPC

curl -X POST https://sdk.flowmails.net/mcp \
  -H "Authorization: Bearer fm_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The tools

ToolScopeWhat it does
list_domainsaddresses:readList the domains the credential can touch
list_addressesaddresses:readList the inbound addresses of a domain
create_addressaddresses:writeProvision a new inbound address
search_emailsmessages:searchSearch message history
get_emailmessages:readRead one message (body, attachments, headers)
send_emailmessages:sendSend mail from a domain-bound address
get_send_statussend_status:readDelivery status of a sent message
wait_for_emailwaits:writeOpen a durable wait on an address + subject
get_wait_statuswaits:readCheck a wait (pending / resolved / expired)
list_eventsevents:readRead the event log (cursor-based)
claim_messagemessages:claimClaim a message so a second agent won't take it
complete_messagemessages:claimMark a claimed message as handled

The scope check runs before the tool does, so a read-only credential cannot send, and a credential bound to one domain cannot touch another.

A typical agent flow

list_domains → create_address → wait_for_email → get_email → send_email → get_send_status

No dashboard visit in between. The MCP server is the protocol-level door onto the same contract the REST API, the SDK and the CLI use.

Links

Registry metadata

This repository is the source of truth for the server's entry in the official MCP Registry: see server.json. The name is io.github.wms-why/flowmails-mcp.

License

MIT — see LICENSE.

No installation packages available.

Remote