# API: Agent mailboxes

| Method | Path | What it does | Scope |
|---|---|---|---|
| DELETE | `/v1/agentmail` | Disconnect AgentMail: its webhook is removed, every agent mailbox turned off and the key deleted (the inboxes stay in your AgentMail account) (web app only) | `integrations:write` |
| GET | `/v1/agentmail` | AgentMail for this organization: connected or not (never the key) and its agent mailboxes | `settings:read` |
| PUT | `/v1/agentmail` | Connect your own AgentMail account (organization owners, signed in): the key is checked, stored encrypted and never returned, and AgentMail's webhook is registered (web app only) | `integrations:write` |
| POST | `/v1/agentmail/check` | Check the saved key with a harmless read, and whether AgentMail still delivers to the webhook (turned back on if AgentMail turned it off) (web app only) | `integrations:write` |
| POST | `/v1/agentmail/mailboxes` | Give an agent its own AgentMail address, or set the organization's agent inbox (a new inbox, or one already in your AgentMail account), with the person responsible for it (web app only) | `integrations:write` |
| PATCH | `/v1/agentmail/mailboxes/:id` | Assign a mailbox to another agent or person, or turn it off or on (web app only) | `integrations:write` |
| POST | `/v1/agentmail/mailboxes/:id/messages` | Send an email from an agent mailbox as its person (or an owner). Policy, suppression, consent, caps and one-click unsubscribe apply as for any send (web app only) | `messages:send` |
| POST | `/v1/webhooks/agentmail/:token` | AgentMail's webhook (Svix-signed): mail received by agent mailboxes, bounces and complaints (no sign-in) | — |

## Examples

### GET /v1/agentmail

AgentMail for this organization: connected or not (never the key) and its agent mailboxes

```bash
curl -s "https://api.closefinch.com/v1/agentmail" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/agentmail`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).