Give your agent an inbox

An inbox for your agent in under five minutes: a key, an address, a message sent, and the reply read back. Everything here works on a free account, and you need no domain.

1. Sign up

Create an account. Onboarding gives your first agent an address on our shared domain, working at once, and shows a block to paste into Claude Code, Cursor, Codex or any chat, with the agent's address and a key in it. If that is all you wanted, you are done.

The rest of this page does the same by hand, from your own code.

2. Make a key

In the app, Developers → API keys. A key is shown once; afterwards the list holds a prefix and nothing else, so store it where you keep your other secrets. Read and send is the level an agent needs.

export PIDGEON_API_KEY=pgn_live_…

cURL needs nothing else. The TypeScript client runs on Node 18 or later and the Python one on Python 3.11 or later; both are generated from the same API, so an operation has the same name in each.

# Nothing to install.

3. Find your address

List the addresses the key reaches. Keep the id of the one signup gave you: waiting for mail needs it.

curl https://pidgeon.ai/api/v1/identities \
-H "Authorization: Bearer $PIDGEON_API_KEY"

To make another address, POST /v1/identities with an address and "type": "agent". Addresses has the rest.

4. Send

from has to be an address the key reaches. Send to an address of your own, so you can answer it in the next step.

curl https://pidgeon.ai/api/v1/messages \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "from": "hello@yourdomain.com",
  "to": "you@example.com",
  "subject": "First one",
  "text": "It works. Reply to this and I will read it."
}'

A 201 comes back with the message id and the thread it landed in. Recipients that fail the send guard come back in rejected rather than as an error, so one bad address does not lose the other four. If the send is refused, GET /v1/agent/setup says what stands in the way and who has to fix it.

5. Wait for the reply

Answer the message from your own mail. GET /v1/messages/await holds the request open until a message arrives at hello@yourdomain.com, or until timeout seconds pass (50 by default, at most 280), so there is nothing to poll.

curl -G https://pidgeon.ai/api/v1/messages/await \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-d identity_id=$IDENTITY_ID \
-d timeout=240

The answer is { message, timed_out, cursor, held_back }. When nothing came in time, message is null: call again with after set to cursor, and nothing that arrives in between is missed.

Next

• Webhooks: in production, mail arriving becomes a signed POST to your code within seconds, instead of a held request.
• Sending and receiving: replies, attachments, HTML.
• MCP: the same inbox as tools for Claude, ChatGPT, Cursor and Codex.
• Mail on your domain: send as agent@yourcompany.com once you want to.