# Give your agent an inbox

> Your agent gets its own address on `@pidgeon.email` in a minute: no domain, no DNS. Connect Pidgeon from your coding agent, the plugin, any MCP client or the API, create an inbox, send, and read the replies.

Source: https://pidgeon.ai/docs/agent-builders

## 1. Connect Pidgeon

Pick one. You need a Pidgeon account, made with your email or Google at [pidgeon.ai/sign-in](https://pidgeon.ai/sign-in); the plugin and the MCP server ask you to sign in the first time.

### Your coding agent

Paste this into Claude Code, Codex, Cursor or any agent that can read the web. It reads these docs and asks before it makes an account or touches DNS.

Give this to your coding agent:

```text
Give this agent an email inbox with Pidgeon. Read https://pidgeon.ai/llms.txt and follow the Email guide. Ask me before creating an account or changing DNS.
```

### The plugin

The MCP server and the skills that tell your coding agent how to use it, in one install. Cursor installs it from the repository: [the plugin](https://pidgeon.ai/docs/sdks.md#plugins).

Claude Code:

```text
/plugin marketplace add pidgeon-ai/pidgeon-plugins
/plugin install pidgeon@pidgeon
```

Codex:

```bash
codex plugin marketplace add pidgeon-ai/pidgeon-plugins
codex plugin add pidgeon@pidgeon
codex mcp login pidgeon
```

Gemini CLI:

```bash
gemini extensions install https://github.com/pidgeon-ai/pidgeon-plugins
```

### Any MCP client

Add `https://pidgeon.ai/mcp` (streamable HTTP). Your client signs you in the first time, or send an API key as `Authorization: Bearer pgn_…`. Then ask: “Make an inbox called scout and email ana@supplier.example from it.” Every tool: [The MCP server](https://pidgeon.ai/docs/sdks.md#mcp).

Claude Code:

```bash
claude mcp add --transport http pidgeon https://pidgeon.ai/mcp
```

Other clients:

```json
{ "mcpServers": { "pidgeon": { "url": "https://pidgeon.ai/mcp" } } }
```

### The API

Sign in, open **API keys** in the dashboard’s menu and make a key with **Admin** access: making inboxes needs it. It is shown once, as `pgn_…`. Keep it on your server as `PIDGEON_API_KEY`. [API keys](https://pidgeon.ai/docs/api-keys.md)

TypeScript:

```bash
npm install @pidgeon-ai/sdk
```

Python:

```bash
pip install pidgeon
```

## 2. Create an inbox

Give it a name: the part before the @. It is live at once on `pidgeon.email`.

TypeScript:

```ts
import { Pidgeon } from '@pidgeon-ai/sdk';

const pidgeon = new Pidgeon({ apiKey: process.env.PIDGEON_API_KEY! });
const inbox = await pidgeon.inboxes.create({ name: 'scout', displayName: 'Scout' });
```

Python:

```python
import os
from pidgeon import Pidgeon

pidgeon = Pidgeon(api_key=os.environ["PIDGEON_API_KEY"])
inbox = pidgeon.inboxes.create("scout", display_name="Scout")
```

curl:

```bash
curl https://pidgeon.ai/v1/email/inboxes \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "scout", "display_name": "Scout"}'
```

Response 201:

```json
{
  "id": "5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "address": "scout@pidgeon.email",
  "kind": "agent",
  "display_name": "Scout",
  "pod_id": "7c6b5a49-3827-4161-9f0e-d1c2b3a49586",
  "agent_id": null,
  "status": "active",
  "hold_suspicious": true,
  "created_at": "2026-11-20T10:02:31.118Z"
}
```

Names are 1–64 of `a-z 0-9 . _ + -`. A name that is taken answers `409`; try another. Every field: [Create an inbox](https://pidgeon.ai/docs/email.md#create).

## 3. Send

TypeScript:

```ts
const sent = await pidgeon.messages.send(inbox.id, {
  to: ['ana@supplier.example'],
  subject: 'Quote for 400 units',
  text: 'Hi Ana, could you send us a quote?',
});
// sent.status: 'sent', or 'held' while a person approves it
```

Python:

```python
sent = pidgeon.messages.send(inbox["id"], to=["ana@supplier.example"],
                             subject="Quote for 400 units",
                             text="Hi Ana, could you send us a quote?")
```

curl:

```bash
curl https://pidgeon.ai/v1/email/inboxes/$INBOX_ID/messages \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": ["ana@supplier.example"], "subject": "Quote for 400 units",
       "text": "Hi Ana, could you send us a quote?"}'
```

A new account sends to 50 people a day. A [verified domain](https://pidgeon.ai/docs/passport.md#verify-domain) raises that, and time raises it again: [Limits by reputation](https://pidgeon.ai/docs/sending.md#limits). HTML, attachments, replies and drafts: [Send mail](https://pidgeon.ai/docs/sending.md).

## 4. Read the replies

Wait for mail: the call answers as soon as something arrives, or after `timeout` seconds (at most 50). Pass `next_since` back to wait for the next.

TypeScript:

```ts
const { data, next_since } = await pidgeon.messages.await(inbox.id, { timeout: 50 });
for (const message of data) console.log(message.from.address, message.subject, message.text);

// Answer in the same thread
await pidgeon.messages.send(inbox.id, {
  to: [data[0].from.address],
  text: 'Thanks, Ana. We’ll take them.',
  replyTo: data[0].id,
});
```

Python:

```python
page = pidgeon.messages.wait(inbox["id"], timeout=50)
for message in page["data"]:
    print(message["from"]["address"], message["subject"], message["text"])

# Answer in the same thread
first = page["data"][0]
pidgeon.messages.send(inbox["id"], to=[first["from"]["address"]],
                      text="Thanks, Ana. We’ll take them.", reply_to=first["id"])
```

curl:

```bash
curl "https://pidgeon.ai/v1/email/inboxes/$INBOX_ID/messages/await?timeout=50" \
  -H "Authorization: Bearer $PIDGEON_API_KEY"
```

On a server, a [webhook](https://pidgeon.ai/docs/webhooks.md) tells you the moment mail arrives (`message.received`). Mail the [Firewall](https://pidgeon.ai/docs/email.md#firewall) calls suspicious waits for a person before the agent reads it.

## Next

- Send from your own domain: [Your own domain](https://pidgeon.ai/docs/email.md#domains).
- Have a person approve what matters: [Drafts and approval](https://pidgeon.ai/docs/sending.md#drafts).
- Try it with mail that never leaves Pidgeon: [Test keys](https://pidgeon.ai/docs/email.md#test-mode).
- Give each of your users their own inboxes: [Platforms](https://pidgeon.ai/docs/platforms.md).
- Optional: give the agent an identity and link its address, and its mail names you as its operator: [Inboxes linked to an agent identity](https://pidgeon.ai/docs/email.md#agent-inboxes).
