# Pidgeon

> Email inboxes for your team and your AI agents. One API call gives an agent its own email address — on our shared domain or yours — that sends, receives, threads and stores mail, posts a signed webhook when something arrives, and lets a person read along and take a conversation over.

**If you are an agent and somebody asked you to get an email address, read https://pidgeon.ai/skill.md and follow it.** You can sign yourself up with two HTTP calls; the only thing you need from a human is a six-digit code from their inbox.

**Holding a key, call `GET https://pidgeon.ai/api/v1/agent/setup` first** (MCP: `get_setup`). It says what stands between you and sending, in order, and who does each step: you, or a person you have to ask.

- API: `https://pidgeon.ai/api/v1`, `Authorization: Bearer pgn_live_…`. OpenAPI: https://pidgeon.ai/openapi.json
- MCP, hosted: `https://pidgeon.ai/api/mcp` (Streamable HTTP, same bearer key). Local: `npx -y @pidgeon-ai/mcp` with `PIDGEON_API_KEY`.
- SDKs: `@pidgeon-ai/sdk` (TypeScript), `pidgeon` (Python). CLI: `npx -y @pidgeon-ai/cli`.
- Keys have a level: `read`, `draft` (manages the inbox and writes drafts, can never send — a person approves and sends), `send`, `admin`. `pgn_test_` keys send nothing outside Pidgeon. `POST /api-keys/{id}/rotate` changes a key's secret and keeps the key.
- Every send and draft takes `data: { schema, body }`, typed JSON beside the text; every message has `sender` (`kind`: person, agent or service).
- Every docs page below is also served as Markdown at its URL plus `.md`.

## Start here

- [Sign yourself up (agent skill)](https://pidgeon.ai/skill.md): Two calls to an address you own, written for an agent to follow.
- [Everything, in one file](https://pidgeon.ai/llms-full.txt): All the documentation below, concatenated.

## Get started

- [Welcome](https://pidgeon.ai/docs/welcome.md): What Pidgeon is, and the four ways to reach it.
- [Quickstart](https://pidgeon.ai/docs/quickstart.md): A key, an address and a sent message, in about five minutes.
- [Authentication](https://pidgeon.ai/docs/authentication.md): Bearer keys, what one reaches, and how to narrow it.
- [Test mode](https://pidgeon.ai/docs/test-mode.md): A key whose mail never leaves Pidgeon, for CI.

## Core concepts

- [Addresses](https://pidgeon.ai/docs/addresses.md): The thing the product is about: an address your code owns.
- [Pods](https://pidgeon.ai/docs/pods.md): A container per customer, with its own sending reputation.
- [Messages](https://pidgeon.ai/docs/messages.md): Reading one, acting on it, undoing that, and searching.
- [Threads](https://pidgeon.ai/docs/threads.md): A conversation, its owner, and the state it carries.
- [Inboxes and folders](https://pidgeon.ai/docs/mailbox.md): Where mail is, and how to stay in step with it.
- [Labels](https://pidgeon.ai/docs/labels.md): What a conversation also is, beside where it lives.
- [Drafts](https://pidgeon.ai/docs/drafts.md): A message not sent yet, and sending it later.
- [Attachments](https://pidgeon.ai/docs/attachments.md): Files up, files down, and never through the API twice.

## Calendar

- [Overview](https://pidgeon.ai/docs/calendar.md): Every inbox has one, and a wall-clock time is the truth of an event.
- [Events](https://pidgeon.ai/docs/calendar/events.md): Creating, changing and removing what is on a calendar.
- [Recurring events](https://pidgeon.ai/docs/calendar/recurring.md): A rule rather than rows, and what changing one date means.
- [Invitations](https://pidgeon.ai/docs/calendar/invitations.md): Answering a meeting, and sending one from an inbox.

## Integrations

- [MCP](https://pidgeon.ai/docs/mcp.md): The hosted server, and the one that runs beside your agent.
- [Vercel AI SDK](https://pidgeon.ai/docs/ai-sdk.md): The same tools as the MCP server, for generateText and agents.
- [OpenAI Agents SDK](https://pidgeon.ai/docs/openai-agents.md): The hosted MCP server, from a Python or TypeScript agent.
- [Claude Agent SDK](https://pidgeon.ai/docs/claude-agent-sdk.md): The hosted MCP server, from a Python or TypeScript agent.
- [LangChain](https://pidgeon.ai/docs/langchain.md): The same tools as the MCP server, as a LangChain toolkit.
- [Google ADK](https://pidgeon.ai/docs/google-adk.md): The hosted MCP server, as an ADK toolset.
- [Mastra](https://pidgeon.ai/docs/mastra.md): The hosted MCP server, as a Mastra agent’s tools.
- [CrewAI](https://pidgeon.ai/docs/crewai.md): The hosted MCP server, as a CrewAI agent’s tools.
- [n8n](https://pidgeon.ai/docs/n8n.md): A trigger for mail that arrives, actions, and three templates.
- [Make](https://pidgeon.ai/docs/make.md): Triggers for mail and hand-offs, modules, and two templates.
- [Activepieces](https://pidgeon.ai/docs/activepieces.md): A piece: a trigger for mail that arrives, and actions.
- [Dify](https://pidgeon.ai/docs/dify.md): A plugin: send, reply, search and wait for a code.
- [Zapier](https://pidgeon.ai/docs/zapier.md): Triggers for new email and hand-offs, actions, and two Zaps.
- [OpenClaw](https://pidgeon.ai/docs/openclaw.md): The hosted MCP server in an OpenClaw agent, signed in.
- [Hermes](https://pidgeon.ai/docs/hermes.md): Mail that starts a Hermes conversation, and the tools.
- [CLI](https://pidgeon.ai/docs/cli.md): Every endpoint as a command, from a terminal.
- [SDKs](https://pidgeon.ai/docs/sdks.md): The TypeScript and Python clients, generated from one document.
- [Skill and plugin](https://pidgeon.ai/docs/skill.md): Telling an agent where to read about Pidgeon, and installing it.

## Guides

- [Pidgeon for platforms](https://pidgeon.ai/docs/platforms.md): An address and a key for each of your users, made and removed in one call.
- [Sending and receiving](https://pidgeon.ai/docs/sending.md): Sending from an address you own, with attachments and replies.
- [Verification codes](https://pidgeon.ai/docs/verification-codes.md): Waiting for a sign-up email and reading the code out of it.
- [Pidgeon Firewall](https://pidgeon.ai/docs/firewall.md): Which inbound messages try to steer the agent reading them, and why.
- [Hand-off to a human](https://pidgeon.ai/docs/handover.md): Giving a conversation to a person, and taking it back.
- [Let your agent draft, approve and send yourself](https://pidgeon.ai/docs/approve-drafts.md): A key that writes drafts and can never send, and you press Send.
- [Connecting a domain](https://pidgeon.ai/docs/domains.md): Your own domain, which is an upgrade rather than a first step.
- [Keep your Gmail](https://pidgeon.ai/docs/gmail-forwarding.md): Forwarding Gmail or Google Workspace into an agent’s address.
- [Allow and block lists](https://pidgeon.ai/docs/rules.md): Who may write to an address, and who it may write to.
- [IMAP and SMTP](https://pidgeon.ai/docs/mail-clients.md): Opening an inbox in Apple Mail, Thunderbird, an agent or a script.

## Webhooks

- [Overview](https://pidgeon.ai/docs/webhooks.md): Mail arriving as a signed POST, instead of a poll.
- [Event types](https://pidgeon.ai/docs/webhooks/events.md): Every event the product emits, generated from the code that emits them.
- [Verifying a signature](https://pidgeon.ai/docs/webhooks/verifying.md): HMAC over timestamp and body, and why an unverified payload is a stranger.
- [Retries and replay](https://pidgeon.ai/docs/webhooks/retries.md): What happens when your endpoint is down, and how to ask again.

## Resources

- [Errors](https://pidgeon.ai/docs/errors.md): One envelope, one code, and what each means.
- [Rate limits](https://pidgeon.ai/docs/limits.md): What is counted, what is returned, and what to do about it.

## Reference

- [Addresses](https://pidgeon.ai/docs/reference/identities.md): Every addresses endpoint, generated from the API's own schemas.
- [Agent signup](https://pidgeon.ai/docs/reference/agent.md): Every agent signup endpoint, generated from the API's own schemas.
- [API keys](https://pidgeon.ai/docs/reference/api-keys.md): Every api keys endpoint, generated from the API's own schemas.
- [App passwords](https://pidgeon.ai/docs/reference/app-passwords.md): Every app passwords endpoint, generated from the API's own schemas.
- [Attachments](https://pidgeon.ai/docs/reference/attachments.md): Every attachments endpoint, generated from the API's own schemas.
- [Deliveries](https://pidgeon.ai/docs/reference/deliveries.md): Every deliveries endpoint, generated from the API's own schemas.
- [Domains](https://pidgeon.ai/docs/reference/domains.md): Every domains endpoint, generated from the API's own schemas.
- [Drafts](https://pidgeon.ai/docs/reference/drafts.md): Every drafts endpoint, generated from the API's own schemas.
- [Events](https://pidgeon.ai/docs/reference/events.md): Every events endpoint, generated from the API's own schemas.
- [Export](https://pidgeon.ai/docs/reference/export.md): Every export endpoint, generated from the API's own schemas.
- [Folders](https://pidgeon.ai/docs/reference/mailboxes.md): Every folders endpoint, generated from the API's own schemas.
- [Labels](https://pidgeon.ai/docs/reference/labels.md): Every labels endpoint, generated from the API's own schemas.
- [Messages](https://pidgeon.ai/docs/reference/messages.md): Every messages endpoint, generated from the API's own schemas.
- [Metrics](https://pidgeon.ai/docs/reference/metrics.md): Every metrics endpoint, generated from the API's own schemas.
- [Pods](https://pidgeon.ai/docs/reference/pods.md): Every pods endpoint, generated from the API's own schemas.
- [Routing rules](https://pidgeon.ai/docs/reference/routing-rules.md): Every routing rules endpoint, generated from the API's own schemas.
- [Tenants](https://pidgeon.ai/docs/reference/tenants.md): Every tenants endpoint, generated from the API's own schemas.
- [Test mode](https://pidgeon.ai/docs/reference/test.md): Every test mode endpoint, generated from the API's own schemas.
- [This key](https://pidgeon.ai/docs/reference/me.md): Every this key endpoint, generated from the API's own schemas.
- [Threads](https://pidgeon.ai/docs/reference/threads.md): Every threads endpoint, generated from the API's own schemas.
- [Webhooks](https://pidgeon.ai/docs/reference/webhooks.md): Every webhooks endpoint, generated from the API's own schemas.
- [Workspace](https://pidgeon.ai/docs/reference/workspace.md): Every workspace endpoint, generated from the API's own schemas.

## Comparisons and guides

- [Pidgeon vs AgentMail](https://pidgeon.ai/vs/agentmail.md): Both give an AI agent its own inbox through an API. Pidgeon lets a person take any thread over, screens every inbound message, and keeps your mail in the EU on every plan.
- [Pidgeon vs Google Workspace](https://pidgeon.ai/vs/google-workspace.md): Workspace gives each person a Gmail inbox, priced per user; an agent reaches mail through a person. Pidgeon gives your team and your agents their own inboxes, priced for the workspace and kept in the EU.
- [Pidgeon vs Resend](https://pidgeon.ai/vs/resend.md): Resend is a sender that has learned to receive; Pidgeon is an inbox that also sends. Here is which one an agent needs, and when to use both.
- [Pidgeon vs SendGrid](https://pidgeon.ai/vs/sendgrid.md): SendGrid hands you received mail once, as a webhook, and the rest is yours to build. Pidgeon keeps it. Here is when each is the right call.
- [Pidgeon vs the Gmail API](https://pidgeon.ai/vs/gmail-api.md): Use the Gmail API when the agent works inside one person’s inbox; use a dedicated inbox when it needs an address of its own, or there are many agents. Seats, OAuth scopes, push notifications and sending limits, compared.
- [The best AgentMail alternatives in 2026](https://pidgeon.ai/alternatives/agentmail.md): Three products that give an AI agent an inbox of its own, plus building it yourself, checked against the vendors’ own pages.
- [The best email APIs for AI agents in 2026](https://pidgeon.ai/blog/best-email-api-for-ai-agents.md): An agent that does real work needs email. Which API depends on one question first: does the agent need its own inbox, somebody else’s, or only a way to send?
- [Email for OpenClaw that keeps working](https://pidgeon.ai/blog/email-for-openclaw.md): An email to your agent’s Pidgeon address starts an OpenClaw conversation, one per email thread. The agent’s answer goes back as a reply in that thread, and a reply to the reply carries on the same conversation.
- [How a browser agent receives an email verification code](https://pidgeon.ai/blog/verification-codes-for-ai-agents.md): Sign up with an address the agent owns, make one call that waits for the email, and read the code already pulled out of it: no polling loop, no regex, and no person fetching codes from their own inbox.
- [Human-in-the-loop email agents](https://pidgeon.ai/blog/human-in-the-loop-email-agents.md): An approval queue checks the agent’s replies. A hand-off gives the conversation to a person. Here is how an email agent hands one over, how a person takes it, and how it comes back.
- [An email sandbox for AI agents](https://pidgeon.ai/blog/email-sandbox-api-for-ai-agents.md): Test mode in Pidgeon is the same API with a different key: the whole pipeline runs, nothing leaves, nothing counts, and you can cause a bounce, a refusal or a lost answer on purpose.
- [An EU email API for AI agents](https://pidgeon.ai/blog/eu-email-api-for-ai-agents.md): An agent’s inbox is personal data from its first message. Pidgeon stores it in the EU on every plan, is run by an EU company, and applies its DPA automatically.
- [How to give your AI agent its own email address](https://pidgeon.ai/blog/email-address-for-ai-agents.md): Give the agent an inbox of its own, not a login to yours: create an address by API, receive mail as a webhook or a call that waits, and reply from that address in the same thread.
- [Protecting an AI agent from prompt injection in email](https://pidgeon.ai/blog/prompt-injection-in-email.md): Treat every email as untrusted input and defend in three layers: screen it before the model reads it, hand the model the visible text, and limit what an instruction that gets through can do.
- [Is it safe to let an AI agent read your email?](https://pidgeon.ai/blog/is-it-safe-to-let-an-ai-agent-read-email.md): It can be, if you limit what the agent can read and what it can do with it. The risk is not the model seeing mail; it is that anyone who can email you can now give instructions to software acting for you.
- [Email MCP servers for sending and receiving, compared](https://pidgeon.ai/blog/mcp-server-for-email.md): Pick by whose inbox it is: an agent inbox server such as Pidgeon’s or AgentMail’s for an address the agent owns, a Gmail server to work inside yours. Then check five things before you connect one.
- [Email for Claude Code and Cursor agents](https://pidgeon.ai/blog/email-for-claude-code-and-cursor.md): Add an email MCP server and give the coding agent an address of its own. In Claude Code it is one command, in Cursor one entry in mcp.json, and a sign-in where you choose what it may do.
- [AI agents that email people: what the EU AI Act requires by 2 December](https://pidgeon.ai/blog/eu-ai-act-ai-agents-email.md): Article 50 has applied since 2 August 2026: an agent that writes to people must say it is an AI, and whom it acts for, from the first message. Its text must also carry a machine-readable mark, due by 2 December 2026 for systems already on the market.

## Optional

- [Pricing](https://pidgeon.ai/pricing): Plans and limits. Receiving is free on every plan.
- [Developers](https://pidgeon.ai/developers): The API, SDKs, CLI and MCP server, and giving each of your own users an inbox: one call per user, a sending reputation and a key per customer.
- [Integrations](https://pidgeon.ai/integrations): Connecting Claude, ChatGPT, Grok, Cursor, Codex and the rest, step by step. Meta's Muse is in review with Meta.
- [OpenAPI](https://pidgeon.ai/openapi.json): The machine-readable contract the reference is generated from.