---
name: agent-inbox
order: 4
description: "Give an AI agent a real email inbox with Sending: create the inbox, read the threads it receives, and reply. Use this when the agent has to receive mail, not just send it."
---

# An inbox for the agent

You need this when the agent has to **receive**: confirmations, customer replies,
notifications from other services. Incoming mail becomes readable threads, not raw
webhooks.

## 1. Create the inbox

```
list_inboxes
create_inbox { name: "support" }
```

The address can live on the shared domain (`agents.sending.dev`) or on a workspace
domain that is already verified **and has receiving enabled**: receiving is a
per-domain toggle under *Communication › Domains*, separate from verification for
sending, because it takes over the inbound mail of the whole domain.

The shared domain needs no configuration: it is the quick way to try this out.

## 2. Read

```
list_threads { inboxId }
get_thread { threadId }
```

Folders are views over the state of the threads and over the outcome of the sender
authentication checks, not labels you have to manage yourself.

## 3. Reply

```
reply_thread { threadId, html }                  # stays in the conversation
send_from_inbox { inboxId, to, subject, html }   # opens a new conversation
```

Use `reply_thread` to answer: it keeps the threading on the recipient's side.
Opening a new thread to answer an existing message loses the thread for whoever is
reading.

Sends from the inbox go through the same pipeline as the rest: they inherit
tracking, the suppression list and the plan quota.

## Who is allowed to write

Allow and block rules apply to the whole workspace:

```
list_email_rules
create_email_rule { type: "block" | "allow", pattern }
delete_email_rule { ruleId }
```

Allow takes precedence over block. Blocked messages are dropped on the way in.

## Being told instead of polling

```
create_webhook { url, events: ["email.received", "email.sent", "email.bounced"] }
list_webhooks
```

Deliveries are HMAC signed (header `Sending-Signature: t=,v1=`): **verify the
signature** before trusting the payload. Prefer the webhook over polling
`list_threads` on a timer.

For volumes: `get_agent_email_metrics`.