io.github.yaotsakpo/inbin

Block (up to ttl_seconds, max 60) for the one confirmation email on a trial inbox created by create_trial_inbox. Pass the exact inbox_address that call returned. The inbox does NOT self-delete or become unusable after a match: it keeps receiving mail and can still be claimed afterward (call claim_trial_inbox any time before it expires) if the human wants to keep using the same address. Call this AFTER you have actually used the address somewhere (signed up, requested a code) -- calling it before that will just expire, since there is nothing to wait for yet. 60 seconds is a hard per-call ceiling, not the inbox's total lifetime: a sender that takes longer than that is not a failure, just call this again with the same inbox_address to keep waiting (the inbox stays valid for its full ~2-week expiry, and you can call this again later too, e.g. to catch a second, later email on the same address). Only treat expired as final once you've retried a few times.

Block (up to ttl_seconds, max 60) for a human to finish the EMAIL+CODE step on the claim_url page from claim_trial_inbox. This NEVER returns a credential, at any status. It returns one of three honest states, not a single 'connected': "claim_pending" (nobody has entered the code yet -- keep waiting or call again), "claimed" (the human proved ownership and a credential was ISSUED, but nothing has used it yet -- a client still needs to be installed with the config from the claim page's 'Advanced' section before anything works), or "client_installed" (some client has actually authenticated with the connection at least once -- a real, observed signal, not an assumption). Each response includes a next_action field telling you exactly what to say or do -- follow it literally rather than guessing. "claimed" is NOT success: do not tell the human it's working until you see "client_installed", and even then, verify it yourself (call list_inboxes or similar through the new connection and read the actual result) before claiming it works for you specifically -- call claim_connection_status later if you need to check again after this chat session, since installing a client can take arbitrarily long and this tool only blocks up to 60s.

Start connecting an agent to this inbox address, permanently -- the SAME address. Works whether this is a brand-new trial inbox OR one that's already been claimed by a different agent before: more than one agent can independently connect to the same inbox, each getting its own separate, revocable connection. Returns a claim_url immediately -- share it in chat right away. The human clicks it, enters their email, enters the one-time code Inbin sends there, and a credential is ISSUED. That is NOT the same as the connection working yet -- the human still has to install that credential into an MCP client's config before anything can actually use it, and you will never see the credential itself, by design. Call await_trial_inbox_claim afterward to see the human finish the email+code step, then claim_connection_status (repeatedly, possibly much later -- installing a client is not instant) to see whether a client has actually started using it. The inbox must still exist (not yet expired) for this to work; it does not need to still be a TRIAL inbox specifically.

Create a temporary inbox with NO Inbin account required at all -- usable before the human has signed up for anything. Returns the inbox address IMMEDIATELY; it does not wait for anything. Use the address to sign up wherever you need a confirmation sent, THEN call await_trial_inbox with that same address to block for the confirmation -- calling this alone does not get you a confirmation. This inbox is NOT tied to any account yet and expires automatically within about two weeks regardless of use. If the human wants to keep using this SAME address permanently, call claim_trial_inbox: no dashboard visit, no key to copy, and more than one agent can independently connect to the same address over time this way.

Read-only, non-blocking check of exactly which state a claim_trial_inbox connection is in RIGHT NOW: "claim_pending", "claimed" (credential issued, unused), or "client_installed" (a client has actually authenticated with it at least once -- real, observed). Never returns a credential. Use this instead of await_trial_inbox_claim when you want to check progress WITHOUT blocking, especially much later than the original chat session -- installing a client into its own config is a human action with no fixed timeline, so polling this occasionally (not in a tight loop) is the right way to check back. Each response includes a next_action field telling you exactly what to say or do.