wait_for_otp
Read-only
Block until an OTP arrives in an inbox and return it, so you can complete signup or login without polling email or writing regex.
Instructions
Block (bounded) until an OTP arrives in inbox_id and return it.
This is the headline tool: use it right after triggering a signup/login
email so you never have to write a polling loop or regex over an email
body. Call it with the ``id`` returned by ``create_inbox``.
``timeout`` is requested in seconds but always clamped to [1, max], where
max is 120 for the local stdio server and 55 for the remote HTTP server:
this is the requested overall wait deadline the SDK aims for, not a hard
wall-clock ceiling on the call — the underlying HTTP transport adds a
small amount of socket-level overhead on top of the clamped deadline
(see the Python SDK's `WAIT_SOCKET_BUFFER`), so the call can return
slightly after the ceiling in practice. On a timeout just call it again.
``min_confidence`` filters out low-confidence OTP extractions.
``since`` (optional) only matches messages that arrived after this point:
an ISO8601 timestamp, unix seconds, or a message id (``msg_...``, meaning
"only messages after that one"; an unknown id falls back to the oldest
message, so prefer a timestamp if unsure). Omitted (the default), the
server matches only messages that arrive during this call — the right
choice for a fresh inbox from ``create_inbox``. When REUSING an inbox for
a second code and you want to catch one that already arrived before this
call, pass either the time just before you triggered this email, or the
``id`` of the last message you saw, so you get the NEW code instead of
missing it.
Side effects: none beyond the long-poll HTTP call(s) needed to satisfy the
wait (``openWorldHint`` — it talks to the live mailsocket API and blocks
for up to ``timeout`` seconds). Returns the OTP string, a confidence
score, the subject/from of the matching message, and its ``id`` /
``received_at`` (chain ``since=<id>`` into the next call on this inbox).
Raises a clean tool error (``WaitTimeout``) if nothing matching arrives
before the deadline.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | ||
| timeout | No | ||
| inbox_id | Yes | ||
| min_confidence | No |