> For an agent: the map of this documentation is at https://escouade.io/en/mail/docs/llms.txt; every page exists in Markdown, at the same address with `.md` appended.

# The workbench in the assistant

> Escouade Mail opens inside the assistant. Once the workbench is open, say “audiences”, “contacts” or “campaign status”: the chat asks for the right page in the same workbench. Reads and actions no longer create a card for every result. There is no separate console.

## The visual entry point

| View | Tool that opens it | What it shows |
|---|---|---|
| Escouade Mail workbench | `open_workspace` | Today, drafts, threads, campaigns, audiences, contacts, inboxes, domains, unsubscribes and the space. |

An instance belongs to the conversation that opened it and to the access that created it. Two conversations do not share a current page. Signing up stays a tool result with no view.

## Navigating with the chat

The assistant opens the workbench once. After that, it reuses the identifier the view published in this conversation's context and calls `navigate_workspace`. It must neither invent this identifier nor reuse one from another conversation.

| Request | Page | Detail argument, if any |
|---|---|---|
| “Today” | `jour` | None |
| “My drafts” | `valider` | None |
| “Mailbox” | `fils` | `thread_id` or `message_id` |
| “Campaigns” | `campagnes` | `campaign_id` |
| “Status of this campaign” | `performances` | `campaign_id`; without it, the list of campaigns |
| “Audiences” | `audiences` | `audience_id` |
| “Contacts” | `contacts` | `query` to search, `email` for a record |
| “Inboxes”, “Domains”, “Unsubscribes”, “Space” | `boites`, `domaines`, `blocages`, `espace` | Depending on the read requested |

The `pending` response means the request has been passed on. It does not prove the page is already displayed. Unsaved input stays in place: the view offers to keep it, or to drop it and open the requested page. A more recent command replaces an older one; a navigation gesture in the view also takes priority over requests already in progress.

The view publishes the page, the selection and the state of the input. It only publishes the active identifier when it is open full size and visible. A hidden view does not consume a request it has not shown.

## `open_workspace`

Opens the instance and loads its first page. Without an argument, it starts on Today. The permissions of the requested read are still required: opening grants no extra access.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `page` | text | no | A section from the table above; `jour` by default. |
| `arguments` | object | no | Arguments of the read, 8 KB at most. For example `{"query":"Alice"}` on the Contacts page. |

The result carries `_navigation`: `instance_id`, `sequence`, `route` and `result`. The read result is that of the business tool, with its usual permissions. See [Reference](https://escouade.io/en/mail/docs/reference/open_workspace.md).

## `navigate_workspace`

Asks for a page in the existing instance, without creating a new card and without sending any e-mail.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `page` | text | yes | The section to display. |
| `arguments` | object | no | Arguments of this section's read, 8 KB at most. |
| `instance_id` | text | yes | Identifier provided by the context of this conversation's workbench. |

The result is a receipt: `status` is `pending`, or `superseded` if a more recent request has replaced it. It does not carry a new view. See [Reference](https://escouade.io/en/mail/docs/reference/navigate_workspace.md).

## `workspace_events`

This tool is reserved for the view. The model must not keep the synchronisation going itself. A wait lasts 18 seconds at most; the instance, the permissions and the token are checked again before answering.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `instance_id` | text | yes | This view's instance. |
| `after_sequence` | integer | yes | The last command received, counting from zero. |
| `ack_sequence` | integer | no | The last command the view has processed. |
| `close` | boolean | no | Releases the instance and wakes up waits when the view closes. |
| `local_navigation` | boolean | no | Marks a local navigation and invalidates earlier requests. |

A new page arrives in `_navigation`. Without a new page, the response carries `unchanged: true`, `instance_id` and `sequence`. A closure returns `closed: true`. The instance expires after 30 minutes without activity; a server restart also requires reopening it. See [Reference](https://escouade.io/en/mail/docs/reference/workspace_events.md) and [Errors](https://escouade.io/en/mail/docs/erreurs.md#application).

## In the conversation, and full size

- **In the conversation**, the card stays short, with no input fields and no full navigation. The lists of campaigns, audiences and contacts show two items at most.
- **Full size**, the workbench has fields, a menu that collapses into icons and horizontal navigation in a narrow window. The content scrolls in its own area. Buttons stay larger on touch screens.
- **Every object carries its activity log**: who did what, and when. See [The activity log](https://escouade.io/en/mail/docs/main-courante.md).
- **Display commands follow the host**: the gestures to enlarge or shrink are adapted to the modes it provides.

## Approving from the view

“Valider” (approve) calls `approve_message` with the version of the draft displayed (`revision`). If the draft has changed, the server refuses with `draft_changed`. “Refuser” (refuse) calls `cancel_message`. Only a message shown in full can be approved.

Without the `approve` permission, the approval gesture is not available. The server checks this permission again on every call. See [Connector](https://escouade.io/en/mail/docs/connecteur.md).

## Display and errors

An HTML e-mail is rendered in an isolated sheet: its external images stay hidden, its links inactive, and no script runs. Its text and its code remain readable. Content received cannot add any gesture to the view. The app uses no external resource and follows the assistant's light or dark theme.

If a read fails, the section stays identifiable and offers to try again. An interrupted synchronisation keeps the page available. An expired instance offers to reopen Escouade Mail; it does not silently create a new card.

## Without view support

An assistant must support MCP Apps to display the workbench. Without that capability, the business tools remain usable through the conversation and return their text and their structured object. Changing pages in a workbench depends on the host and on an active instance.

## For those building a client

- `open_workspace` announces `_meta.ui.resourceUri` and `_meta["openai/outputTemplate"]` with `ui://subagent/workspace-v12.html`. It is also offered as a conversation panel entry to hosts that support it.
- `navigate_workspace` is visible to the model and to the app. `workspace_events` announces `_meta.ui.visibility: ["app"]`; both have no visual resource.
- Tools usable from the view announce the `app` visibility and `_meta["openai/widgetAccessible"]: true`.
- Resources are read with `resources/read` and listed with `resources/list`. Their type is `text/html;profile=mcp-app`. The old addresses from v2 to v10 remain readable for cards already present; they serve the current app.
- Data kept to speed up a read stays partitioned by access. A change in permissions invalidates this context; a page is not authorised because it was in a cache.

## Tools without a new view

The tools below return data and text. Their results can feed the existing workbench; they no longer ask the host to display an extra card.

- Sign-up: `sign_up`, `verify`, `attach_human`.
- Navigation and preparation: `navigate_workspace`, `workspace_events`, `workspace_snapshot`.
- Today and inboxes: `inbox_status`, `activity_report`, `list_events`, `list_inboxes`, `create_inbox`, `update_inbox`, `delete_inbox`, `request_inbox_review`, `create_app_password`, `list_app_passwords`, `revoke_app_password`.
- Domains: `add_domain`, `verify_domain`, `list_domains`, `domain_quality`, `remove_domain`, `inspect_domain`.
- Messages: `send_email`, `list_threads`, `get_thread`, `reply_to_thread`, `classify_thread`, `close_thread`, `get_message`, `list_drafts`, `update_draft`, `approve_message`, `cancel_message`, `attach_files`, `remove_attachment`, `get_attachment`.
- Contacts and audiences: `list_contacts`, `get_contact`, `save_contact`, `set_contact_audiences`, `list_audiences`, `get_audience`, `save_audience`, `import_contacts`, `remove_audience_contact`.
- Campaigns: `list_campaigns`, `list_campaign_templates`, `get_campaign`, `preview_campaign`, `campaign_metrics`, `save_campaign`, `campaign_action`, `campaign_history`, `save_campaign_template`.
- Unsubscribes: `list_suppressions`, `add_suppression`, `remove_suppression`.
- Space and plan: `get_settings`, `update_settings`, `list_keys`, `create_key`, `revoke_key`, `set_webhook`, `remove_webhook`, `event_feed`, `close_space`, `billing_status`, `subscribe`, `cancel_subscription`.