# Welcome

> What Pidgeon is — a mailbox your code creates in one call that receives, threads and webhooks your mail — 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](https://pidgeon.ai/docs/quickstart.md) 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](https://pidgeon.ai/docs/webhooks.md) 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](https://pidgeon.ai/docs/authentication.md) 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](https://pidgeon.ai/docs/handover.md), 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 five
places. Four are generated from one document; the MCP server's tools are
chosen by hand from the same operations, because a model reads every tool's
description on every call.

```text
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 the four generated ones, so a method you
find in one tells you what to look for in the others. The [API reference](https://pidgeon.ai/docs/reference.md) 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`](https://pidgeon.ai/skill.md) — it is written for you
rather than for them, and it starts by telling you to sign yourself up: two
calls, and the only thing you need from your human is a six-digit code from
their inbox.

## Where to go next

- **[Quickstart](https://pidgeon.ai/docs/quickstart.md)** — the five minutes.
- **[Addresses](https://pidgeon.ai/docs/addresses.md)** — the thing the product is about.
- **[Webhooks](https://pidgeon.ai/docs/webhooks.md)** — how mail reaches your code.
- **[MCP](https://pidgeon.ai/docs/mcp.md)** — giving an agent the mailbox directly.