Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Welcome

What Pidgeon is, and the four ways to reach it.

Mailboxes for AI agents. An inbox your code creates in one call, that receives and threads mail, holds the conversation — history, labels, search — and posts you a signed webhook the moment something arrives.

Sending is a message. This is an inbox.

Start here

sh
npm install -g @pidgeon-ai/cli
pidgeon identities list

Quickstart is a key, an address and a sent message in about five minutes. You do not need a domain to begin — signing up gives you an address with a welcome message already in it, and your own domain is an upgrade for when you want mail to come from you.

What is different about it

Mail arriving is an HTTP request. You do not poll. Webhooks carry ids rather than bodies, are signed, and are replayable for ninety days.

A key reaches what it names. Not the account — a list of addresses, with a ceiling: a key can read and not send, and a key can mint a narrower key and never a wider one. Authentication has the ladder.

It opens in a real mail client too. There is one at /app, and IMAP and SMTP for Apple Mail, Thunderbird or anything else — with app passwords rather than a raw API key. An agent that gets stuck can hand a conversation to a person, who answers in the same thread and hands it back.

The shape of the API

Everything is a resource and everything is reachable the same way from four places, because all four are generated from one document.

REST        https://pidgeon.ai/api/v1
TypeScript  npm install @pidgeon-ai/sdk
Python      pip install pidgeon
CLI         npm install -g @pidgeon-ai/cli
MCP         https://pidgeon.ai/api/mcp

An operation has the same name in each, so a method you find in one tells you what to look for in the others. The API reference is generated from the schemas the API validates with, which is why it cannot describe an endpoint that is not there.

If you are an agent reading this

Somebody has asked you to get your own email address. Read pidgeon.ai/skill.md — it is written for you rather than for them, and it starts by telling you to ask your human for a key, because addresses live on a domain somebody owns.

Where to go next

  • Quickstart — the five minutes.
  • Addresses — the thing the product is about.
  • Webhooks — how mail reaches your code.
  • MCP — giving an agent the mailbox directly.