# How to give your AI agent its own email address

> 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.

## Why not your own inbox

With Pidgeon the address is one API call, and three inboxes are free.

The alternative most people try first is OAuth into their own Gmail or Outlook. It works for an assistant that triages your mail. It is the wrong shape for an agent that does its own work, for three reasons:

- **It reads everything.** A Gmail scope that lets an agent read mail lets it read all of it: your bank, your doctor, your password resets. An agent that only needs supplier replies still holds the rest.
- **It speaks as you.** Every email the agent sends is from you. When it gets something wrong, the person on the other end thinks you did.
- **It does not multiply.** Ten agents are ten people's inboxes, or ten paid seats. A product that gives each of its customers an agent needs an address per customer.

An address of its own fixes all three. The agent sees only mail sent to it, signs as itself, and a new one is an API call.

## Create the address

Sign up at [pidgeon.ai](https://pidgeon.ai/signup) and you already have one address on the shared domain, `pidgeon.email`. Or let the agent sign itself up: two HTTP calls and a six-digit code from a person, described in [`skill.md`](https://pidgeon.ai/skill.md).

A key with full access creates more:

```sh
curl https://pidgeon.ai/api/v1/identities \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "scout@pidgeon.email",
    "display_name": "Scout",
    "type": "agent"
  }'
```

The answer carries the address's `id`, which every later call names as `identity_id`. A domain of your own is free on every plan, and it is what makes the agent's mail come from `scout@yourcompany.com`; the [domains guide](https://pidgeon.ai/docs/domains.md) lists the DNS records to add.

In TypeScript, with `npm install @pidgeon-ai/sdk`:

```ts
import { client, identitiesCreate } from '@pidgeon-ai/sdk';

client.setConfig({ auth: () => process.env.PIDGEON_API_KEY! });

const { data } = await identitiesCreate({
  body: { address: 'scout@pidgeon.email', display_name: 'Scout', type: 'agent' },
  throwOnError: true,
});
const identityId = data.data.id;
```

## Receive mail

There are two ways, and most agents use both.

**A webhook, for an agent that runs on its own.** Register an endpoint for `message.received` and each email becomes a signed HTTP request to your code within seconds. The [webhooks guide](https://pidgeon.ai/docs/webhooks.md) shows how to verify the signature.

**A call that waits, for an agent in the middle of a task.** An agent that has just emailed a supplier, or submitted a sign-up form, can wait for the answer in one request:

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

const { data: waited } = await messagesAwait({
  query: { identity_id: identityId, body: 'clean', timeout: 120 },
  throwOnError: true,
});

if (waited.data.message) {
  console.log(waited.data.message.subject, waited.data.message.text);
}
```

`body: 'clean'` returns the text with anything a person could not see removed: hidden HTML, invisible characters. An email is text a stranger wrote, and the agent is about to read it. [Prompt injection in email](https://pidgeon.ai/blog/prompt-injection-in-email) covers what else is checked.

## Reply in the same thread

A reply names the message it answers. Pidgeon reads the recipients, the subject and the thread headers off it, so the other side's mail client files the answer under the same conversation:

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

await messagesReply({
  path: { id: waited.data.message!.id },
  body: { text: 'Thanks. The order is confirmed for Thursday.' },
  throwOnError: true,
});
```

When the supplier answers again, the next wait or webhook carries the same thread id, and the agent has the whole conversation to read before it replies.

## From an agent, without code

If the agent is Claude Code, Cursor, Codex or anything else that speaks MCP, it does not need the SDK. Pidgeon's hosted MCP server is a URL:

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

The first call opens a sign-in where you choose what the agent may do: read, read and send, or full access, on one address or all of them. The agent then has `create_address`, `await_message`, `send_message` and `reply_to_message` as tools. [Email for Claude Code and Cursor](https://pidgeon.ai/blog/email-for-claude-code-and-cursor) walks through it.

## Keep a person in reach

An agent with its own address still answers to somebody, and the address can say how:

- **A key that can only draft.** A `draft` key reads and writes drafts and can never send; a person reviews and sends from the dashboard.
- **Approval for strangers.** With `send_approval: "first_contact"`, a first email to somebody the address has never written to or heard from waits for a person.
- **A thread a person can take.** Every conversation has an owner, `agent` or `human`. When a person takes one over, the agent's sends in it are refused until it is handed back.

## Other ways to do it

Pidgeon is one agent inbox API among several: AgentMail is the best known, and [the roundup of email APIs for AI agents](https://pidgeon.ai/blog/best-email-api-for-ai-agents) compares them. A Google Workspace user per agent works too, at a seat each; [Pidgeon vs the Gmail API](https://pidgeon.ai/vs/gmail-api) has the limits. And you can build it yourself on Amazon SES, if storage, threading, search and deliverability are work you want.

Whichever you pick, the rule is the same: the agent gets its own address, and yours stays yours.

## Questions

### Should an AI agent use my email account?

Usually not. OAuth into your inbox lets the agent read all of it and send as you. An agent that does its own work is safer and simpler with an address of its own, which sees only mail sent to it.

### How do I create an email address for an AI agent?

With an agent inbox API, in one call. In Pidgeon, POST /v1/identities with an address and type "agent" creates it; the agent can also sign itself up from pidgeon.ai/skill.md with a six-digit code from a person.

### Can the agent use my own domain?

Yes, on every Pidgeon plan, free included. Add the domain and its DNS records, and the agent’s mail comes from an address on it. Until then it can use the shared pidgeon.email domain.

### How much does an AI agent email address cost?

Three Pidgeon inboxes are free, and receiving is free on every plan. Ten inboxes are €20 a month. A Google Workspace user per agent starts at $7 a month each.