Get the OTP, not the email

Give your signup test, script or AI agent a real inbox address. One API call waits until the code arrives, then hands back the code or the magic link as JSON, so you can drop the shared Gmail account and the IMAP-plus-regex script that reads it.

For testing apps you own or are authorized to test. Not for creating accounts on services you don't control.

Start free Try it without signup

Free plan available. Paid plans are paused.

200 GET /api/v1/inboxes/{id}/messages/wait?require=otp
{
  "data": {
    "id": "msg_Z5hG9US_6l2IfBBendvv5F3n",
    "inbox_id": "inbox_sM7DQ3X5RSMdb4QThg0ECI6E",
    "from": "Acme <no-reply@acme.dev>",
    "subject": "Your Acme verification code",
    "received_at": "2026-10-02T06:23:26Z",
    "otp": "482193",
    "otp_confidence": 0.95,
    "otp_context": "Your Acme code is 482193",
    "magic_link": null
  }
}
200 GET /api/v1/inboxes/{id}/messages/wait?require=link
{
  "data": {
    "id": "msg_hhgLcirJyxOvcOfvygxtTZrf",
    "inbox_id": "inbox_-ppgraB2rrtW-daLNz527tLz",
    "from": "Acme <no-reply@acme.dev>",
    "subject": "Sign in to Acme",
    "received_at": "2026-10-02T08:36:32Z",
    "otp": null,
    "otp_confidence": 0.0,
    "otp_context": null,
    "magic_link": "https://acme.dev/auth?token=9fK2xQ7vLp4Tz8Wb"
  }
}

otp_confidence is a heuristic score: 0.95 next to a word like “code”, 0.35 for a bare number. More in the docs →

9 of 22 fields shown. The rest include to, links, text and html.

How a signup test uses it

  1. Create an inbox

    One POST returns an inbox id and a random address on in.inboxpipe.net (why this domain). The free plan includes 3 inboxes; the first is created for you when you verify your email, and you can reuse it on every run: a wait only matches mail received after its since point (step 3), so an earlier run's code is not returned. Paid plans hold more inboxes, so parallel runs can each get their own.

    POST /api/v1/inboxes → "address": "eqxwebxjzv8kfrvo@in.inboxpipe.net"

  2. Type the address into the form you are testing

    Your test fills in the email field and submits, the way a user would. Your app sends its normal verification email and needs no changes; mailsocket accepts it and pulls out the code and the link as it arrives.

    page.fill("#email", inbox["address"]) page.click("text=Create account")

  3. Call wait() for the code

    The request stays open for up to 25 seconds. It answers 200 with the message (the JSON above) the moment a code is found, or 204 when time runs out, and you call it again. By default only mail that arrives after the call starts matches; pass since with a timestamp from just before the submit so a fast email is not missed. For a magic link, use require=link.

    GET /api/v1/inboxes/{id}/messages/wait?require=otp → 200 {"data": {"otp": "482193", …}}

The same flow with the Python SDK

The sample reuses your existing inbox; create_inbox() makes a new one when your plan has room. wait_for_otp() re-issues the 25-second long-poll for you until a code arrives or its own timeout (60 seconds by default) runs out, then returns a WaitResult.

The sample passes since with the time just before the submit, so a code that arrives before the wait starts is still matched and an older code in the reused inbox is not. result.confidence is the message's otp_confidence; to skip bare numbers, add min_confidence=0.9.

For a magic link, call wait_for_link() and read result.magic_link.

signup_test.py
import time
from mailsocket import Client

client = Client("ms_live_...")    # your API key
inbox = client.list_inboxes()[0]  # or create_inbox()

started = time.time()
page.fill("#email", inbox["address"])
page.click("text=Create account")

result = client.wait_for_otp(inbox["id"], since=started)
print(result.otp)         # 482193
print(result.confidence)  # 0.95

Call it from your language, your agent, or n8n

The SDKs and the MCP server wrap the same REST endpoints, so a test written against one behaves the same with another. SDK source on GitHub

AI agents can get a key without signing up: one call to POST /api/v1/agents/register returns a key and an inbox. How it works

  • Python SDK

    pip install mailsocket

    Python 3.9+, no dependencies.

    Python docs PyPI package

  • TypeScript SDK

    npm i mailsocket-sdk

    Node 18+, typed.

    TypeScript docs npm package

  • n8n

    Settings → Community nodes → Installn8n-nodes-mailsocket

    Create an inbox and wait for the code in a workflow. Also usable as an AI Agent tool.

    n8n node n8n install guide

  • MCP server

    Local, over stdiopip install mailsocket-mcp Hosted, no installhttps://mcp.mailsocket.app/mcp

    Gives Claude, Cursor and other MCP clients tools to create an inbox and wait for the code or link.

    MCP setup PyPI package

  • REST API

    Auth headerAuthorization: Bearer <key>

    curl, fetch, requests, any HTTP client.

    OpenAPI spec API reference

What it does, and what it doesn't

What it does

  • Receives email at addresses on in.inboxpipe.net.
  • Extracts the one-time code and the magic link from each message.
  • Returns them as JSON through the wait endpoint, the REST API, or a Server-Sent Events stream.
  • Gives you the full text and HTML body too, when you need more than the code.

What it does not do

  • Send email. The service only receives.
  • Receive SMS or phone-number codes.
  • Open or click magic links. It extracts them; your code decides what to do.
  • Replace a personal mailbox. There is no IMAP or POP access.

Try it on your own signup test

The free plan needs no card. Create an inbox, run the test, and look at what wait() sends back.

Start free Try it without signup

Free plan limits

Inboxes
3 inboxes
Messages
1,000 / month
Retention
1 day
Concurrent waits
2
Webhooks
Not included