MCP email inbox: let an AI agent confirm its own sign-up

What an agent needs that a REST API does not give it

There is a REST API on this site, and a programmer integrating it will do fine. An agent will not: it cannot open the reference, decide which of three endpoints it wants, and hand-roll a request with the right query string. It asks a server what it can do, receives machine-readable schemas, and calls one.

So everything the service does is exposed a second time, as tools. Six of them, and no state to manage between calls:

The server also answers initialize with a short paragraph of instructions, which most clients feed straight to the model. An agent therefore arrives already knowing what this service is for and what its one real caveat is, without anybody writing that into a prompt.

Connect a client in one line

The endpoint is one URL, and there is nothing to sign up for on the public domains. Every MCP client takes the same shape of configuration — Claude Desktop, Claude Code, Cursor, Continue, the OpenAI Agents SDK and anything else that speaks the protocol:

{"mcpServers":{"grabmail":{"url":"https://grabmail.io/mcp"}}}

The transport is Streamable HTTP: one POST carrying JSON-RPC 2.0, one JSON reply, no stream held open. You can therefore check the whole thing from a terminal before any agent is involved:

curl -sX POST https://grabmail.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Clients that look for a server before asking a human will find /.well-known/mcp.json on the domain, which names the same endpoint and its transport.

The whole sign-up loop, in four tool calls

This is the sequence almost every agent needs, and there is nothing else to it:

1. Call create_inbox. Back comes an address, an alias, the domain, and a note telling the agent which of the two to hand over. Nothing was created — the mailbox begins to exist when the first message lands in it.
2. Put the alias in the form. The service being signed up to gets a working address that reaches the mailbox and cannot be used to read it.
3. Call wait_for_message with the address. Immediately after submitting, not on a timer. It blocks; it does not poll in a loop the agent has to write.
4. Read the code out of the message. The full body comes back with the wait, so there is usually no second call at all — read_message is only needed for something that arrived earlier.

Why wait_for_message returns before the mail does

It is the tool that makes an agent workable, and the one whose behaviour surprises people, so it is worth a minute. A call looks like this:

curl -sX POST https://grabmail.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":
        {"name":"wait_for_message",
         "arguments":{"address":"demo.5kuqarzuch@grabmail.io",
                       "subject_contains":"code"}}}'

It blocks for up to 25 seconds. If nothing has arrived by then, it does not fail — it comes back with a plain answer and asks to be called again:

{
  "timed_out": true,
  "waited_seconds": 25,
  "message": null,
  "note": "Nothing arrived yet. Call wait_for_message again ..."
}

Why bounded at all

Every second of waiting is a server worker doing nothing but sleeping, and there is a fixed number of them. A wait that could last five minutes would be one agent holding a slot that a hundred others need. 25 seconds also sits inside every client’s default timeout, so the call returns rather than the client giving up on it.

Only 8 waits at once

Past that the tool answers immediately with timed_out and a note saying so. Being told to come back is better than being queued behind seven other agents with no way to know it.

Filtering, so the wrong mail does not end it

from_contains and subject_contains make the wait ignore anything else that lands meanwhile. since_id is the one to pass when the mailbox already had something in it: hand it the newest id already seen and only genuinely new mail will satisfy the call.

Hand out the alias, poll the address

Every mailbox here has a second address, twelve characters long, that delivers into the same mailbox and cannot read it. That distinction matters far more for an agent than for a person, because an agent will happily paste whatever it was given into whatever field it finds.

So create_inbox does not simply hand back an address and hope. It returns both, and a next_step saying which is which — the agent reads its own tool result, so the instruction arrives where it is needed rather than sitting in a documentation page nobody in the loop can read.

What to put in the agent’s own instructions

The tools describe themselves well enough that a capable model gets this right unprompted. Five lines make it reliable rather than likely:

• One address per sign-up. Not one address reused everywhere: a mailbox holding six services' mail is six confirmations an agent has to tell apart, and one leak that exposes all of them.
• Give out the alias, never the address. Worth saying explicitly even though the tool result says it too.
• Call wait_for_message straight after submitting, and call it again on timed_out rather than treating that as a failure. Two or three times is normal.
• Pass since_id when the mailbox is not new, or an old message satisfies the wait and the agent reads a code that expired an hour ago.
• Delete the message once the code is used. Not required — everything goes in 5 days anyway — but it closes the window early and it costs one idempotent call.

Written as an instruction block, that is about as long as this:

When you need an email address, call create_inbox and hand out the ALIAS it
returns, never the address. Immediately after submitting the form, call
wait_for_message with the address. If it answers timed_out, call it again —
that is normal and nothing was lost. Pass since_id if the mailbox already had
mail in it. Delete the message once the code has been used.

The limits worth knowing before you build on it

All of them are published rather than discovered, and none of them has a plan that raises it:

There is no sending endpoint and no tool for one. This service receives only, which is what keeps an unauthenticated mailbox from becoming a spam relay — so an agent that needs to reply to a human needs a real mailbox somewhere else.

When a form refuses the public domains

Plenty of services keep lists of disposable-mail domains, and the three public ones here are on them. An agent meets this as a form that rejects the address it was just given, or worse, accepts it and never sends anything.

The durable answer is a domain you own. One MX record turns every address on it into a mailbox here, it is on nobody’s list because it is printed nowhere on this site, and the same six tools work on it unchanged — create_inbox is the only one that does not, since it invents addresses on the public domains. The agent simply uses you-pick-it@your-domain and calls wait_for_message on that.

MX record for your domain10 smtp.grabmail.ioCopy

The full walk-through is here — the record, what publishing it proves, and the limits of a mailbox with no password on it.

What not to let an agent do with this

The honest part, and the part that saves an afternoon:

• Nothing you would need to recover. Anything holding money, identity or work. The mailbox is empty again in 5 days and readable by whoever knows the address, so a password reset sent to it next year reaches nobody — or somebody else.
• Not as a second factor. A mailbox with no password on it is not a factor.
• Not for anything private. Not because we read it, but because the address is the only secret in play and an agent may well have written it into a log, a transcript or a commit message.
• Not for volume. An agent opening accounts by the hundred is the behaviour every blocklist exists for, and it is the fastest way to get the public domains refused for everybody else.

Used for what it is — the confirmation step that stands between an agent and the thing it was actually asked to do — it removes the one step that reliably stops it.

Questions