Get started

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.

1. Connect Pidgeon

Pick one. You need a Pidgeon account, made with your email or Google at 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.

Prompt for your coding agent
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.

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

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.

claude mcp add --transport http pidgeon 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

npm install @pidgeon-ai/sdk

2. Create an inbox

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

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' });

Names are 1–64 of a-z 0-9 . _ + -. A name that is taken answers 409; try another. Every field: Create an inbox.

3. Send

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

A new account sends to 50 people a day. A verified domain raises that, and time raises it again: Limits by reputation. HTML, attachments, replies and drafts: Send mail.

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.

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,
});

On a server, a webhook tells you the moment mail arrives (message.received). Mail the Firewall calls suspicious waits for a person before the agent reads it.

Next