wait_for_link
Read-only
Blocks until a magic link email arrives in the inbox, then returns the link text, sender, and subject. Use it for signup or login flows that email clickable links instead of numeric codes.
Instructions
Block (bounded) until a magic link arrives in inbox_id and return it.
Use this instead of ``wait_for_otp`` when the target flow emails a
clickable magic link rather than a numeric/alphanumeric code. The link is
returned as text, NOT followed by this tool — fetch it yourself (e.g. via
a headless browser or ``curl``) however your task needs.
``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 — the underlying HTTP transport adds a small amount of
socket-level overhead on top of the clamped deadline, so the call can
return slightly after the ceiling in practice. On a timeout just call it
again.
``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 link 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 link 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 magic link, 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 no link arrives before the deadline.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | ||
| timeout | No | ||
| inbox_id | Yes |