Verification codes
Your agent signs up. The code is already out.
An agent fills in a sign-up form with an address it owns. One request waits for the email that comes back, and returns it with the code or confirmation link already pulled out.
On every plan. The address stays the agent’s, for the next code too.
01 · How it works
3 steps.
01 · Start waiting
The request holds open until a message with a code arrives at the address — 60 seconds by default, up to 280. Start it before you submit the form, so a fast service cannot answer first.
curl -G https://pidgeon.ai/api/v1/messages/await \ -H "Authorization: Bearer $PIDGEON_API_KEY" \ -d identity_id=$IDENTITY_ID \ -d has_code=true \ -d timeout=12002 · Submit the form
With the agent’s own address. The answer comes back when the mail does.
03 · Read the code
Candidates come most likely first, with spaces removed. If the service refuses the first, the second is right there, and so is the message.
const code = data.data.message?.extracted.codes[0]?.value;
02 · What it does
Why verification codes works this way.
One call, no webhook server
The request waits for the mail. When nothing comes in time it returns a cursor, and calling again with it misses nothing that arrived in between.
Codes and links
Numeric and alphanumeric codes, and verification, confirmation and sign-in links first — unsubscribe and social links left out.
An address it keeps
The account your agent just created will email again — the next code, a reset, a receipt. A throwaway inbox is gone by then; this one is not.
03 · Questions
Asked before trusting it.
- How long does the request wait?
- 60 seconds by default and up to 280. If nothing arrives in time it returns timed_out with a cursor; call again with that cursor and nothing that arrived in between is missed.
- What if the email contains more than one number?
- Pidgeon returns every candidate, most likely first, so an order or phone number above the code does not hide it. Codes are read from the new text of the message, never from quoted history.
- Can my agent do this over MCP?
- Yes. The await_message tool waits for the next message the same way and returns it with the codes and links already extracted.
04 · More