Docs Register
Product overview

Agent runtime and MCP

Wait once. Get the answer.

Your agent asks for the message it needs. InboxSpec waits on the server, then returns the code, link, and useful context in one result.

Try it freeSee the 3-step flow

No polling loop. Waiting is not metered or rate limited.

Agent run · ci-4182waiting
MCPwait_for_message60s max
matched641 ms
Verify your email Acme · noreply@acme.example
Code482913
Linkverify

The response is the artifact. The next agent step can use it immediately.

Connect to hosted InboxSpec with REST examples for JavaScript, Python, Java and more. SDK and CLI require access to our private release. Connect your agent with hosted MCP and a project key. Choose a connection method.

1 call instead of a polling loop2 clear outcomes matched or timeout4 equal interfaces MCP, REST, SDK, CLI

Three steps, no email plumbing.

You supply a run identifier and the message you expect. The response gives your agent a next action, not another search task.

1

Create a safe destination

Give this run its own inbox.

Use a stable run ID such as ci-4182. Parallel tests stay separate and cleanup can target the whole run.

Inbox readysignup.ci-4182@inbox.acme.test
2

Trigger your product

Use the inbox like a real customer address.

Sign up, reset a password, invite a teammate, or run any flow that sends inbound email.

Your applicationInboxSpec inbox
3

Block on the result

Ask for exactly what the agent needs.

Match the subject, require a code, or look for a verification link. One call returns as soon as the right message arrives.

Matched in 641 msmessage.codes[0] → 482913

Use your interface

One job, spelled four ways.

MCP is a first-class interface over the same core as REST, SDK, and CLI. Switching tools does not change the match rules or outcomes.

  • MCP tools describe the workflow to the model.
  • REST makes the contract visible over HTTP.
  • The TypeScript SDK keeps both outcomes typed.
  • CLI exit codes make shell automation predictable.
Best forAutonomous agents and tool-using assistants
wait_for_message({
  inbox: "signup.ci-4182@inbox.acme.test",
  match: { subject_contains: "verify", has_code: true },
  timeout_ms: 60000
})
Every interface returns the same core result{ status: "matched", message: { codes, links, text }, waited_ms }

Predictable outcomes

“No message” never hides the reason.

A timeout is a useful result. A wrong inbox, spent quota, or invalid request is a typed error. Your agent can choose a repair instead of guessing and retrying forever.

matchedThe right email arrived.Use the code, link, or text.
timeoutInbox and quota are valid, nothing matched.Read the hint and check the sender or match.
inbox_not_foundThe inbox reference is wrong.Fix the address. Do not retry.
quota_exceededYour read allowance is spent.Inspect Usage and wait for the reported reset.

Token-bounded by design

The email cannot take over the context window.

InboxSpec puts the useful preview in the response and gives the complete body its own URL. The agent asks for more only when the task needs it.

text.preview2,000 characters
inlinefull body via URL
truncated: truetotal_bytes: 18240url: /body?format=text

Start with one real flow

Prove signup email without building a polling loop.

Use hosted MCP with your project key to create an inbox and wait for mail from your agent. REST, SDK and CLI are also available. Follow the setup guide before using these illustrative fragments.

  1. 1
    Create a free project

    Save your project key and choose a supported client from the setup guide.

  2. 2
    Make an inbox for the run

    Use a name your logs and agent can recognize.

  3. 3
    Wait for the verification message

    Branch on matched or timeout. Both explain what happened.

Start freeOpen setup guide