# Mail Navigation

> The left column of a mail client agents work in too: account, compose and search, folders with quiet counts, smart views written as sentences (hover shows the query an agent would run, + compiles a new one as you type), each agent with a dot when it needs you and a pause control, and an Agent view row. Folds into an icon rail with ⌘B.

- Slug: `mail-nav`
- Category: [Email](https://www.assembli.design/category/email.md)
- Type: block
- Tags: mail, sidebar, navigation, agents, smart-views, collapsible
- npm dependencies: lucide-react
- shadcn/ui dependencies: button, input, kbd, @assembli/avatar, @assembli/tooltip
- Live preview: https://www.assembli.design/preview/mail-nav
- Page: https://www.assembli.design/components/mail-nav

![Mail Navigation preview](https://www.assembli.design/thumbnails/mail-nav-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `account` | `{ name: string; email: string; avatar?: string }` | `{ name: "Ines Moreau", email: "ines@larkspur.co" }` |  |
| `current` | `string` | `"inbox"` | The open destination: a folder id, `view:<id>` or `agent:<id>`. |
| `onNavigate` | `(id: string) => void` |  |  |
| `counts` | `Partial<Record<FolderId, number>>` | `{}` | Counts per folder (unread for Inbox, totals elsewhere). |
| `views` | `SmartView[]` | `[]` | Saved searches. The section shows only when there are some. |
| `pages` | `NavPage[]` | `[]` | Destinations listed above the folders. `current` matches their `id`. |
| `agents` | `NavAgent[]` | `DEFAULT_AGENTS` |  |
| `onAction` | `(action: MailAction) => void` |  | `pause_agent`, `resume_agent`, `create_view`, `compose`, `switch_account`, `search`, `agent_view`, all with a human actor. |
| `onSearch` | `() => void` |  | Called by the Search row (also emitted as `search`). Wire it to a command bar. |
| `onAgentView` | `() => void` |  | Shows an "Agent view" row at the foot of the nav (also emitted as `agent_view`). |
| `agentViewOpen` | `boolean` |  | Whether the agent view is open, for the row's pressed state. |
| `toQuery` | `(sentence: string) => string` | `sentenceToQuery` | Turns a sentence into a search query for "New view". The default knows a handful of phrases. |
| `actorName` | `string` |  | The person acting, for `actor` on emitted actions. Defaults to the account name. |
| `collapsed` | `boolean` |  |  |
| `defaultCollapsed` | `boolean` | `false` |  |
| `onCollapsedChange` | `(collapsed: boolean) => void` |  |  |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/mail-nav/mail-nav.tsx` and installs dependencies):

```bash
npx shadcn@latest add @assembli/mail-nav
```

Registry item JSON: https://www.assembli.design/r/mail-nav.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.