> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> The agent inbox — threading, triage state, full-text search, attachments, and mailboxes on a managed domain.

# Conversations

A conversation layer sits on top of the inbox and outbound tables so a support agent — human
or AI — can triage **threads** instead of individual messages.

## Threading

Inbound mail is threaded by RFC headers (`Message-ID`, `In-Reply-To`, `References`) first,
falling back to subject plus participants within `CONVERSATION_MATCH_WINDOW_DAYS` (default 30)
when headers are missing.

## Triage state

Each conversation carries:

| Field      | Values                                                        |
| ---------- | ------------------------------------------------------------- |
| `status`   | `open`, `pending`, `closed`, `snoozed` (with `snoozed_until`) |
| `assignee` | An agent identifier, or unassigned                            |
| `tags`     | Freeform                                                      |
| `is_read`  | Read flag                                                     |
| Summaries  | `participants`, `last_message_at`, `message_count`            |

A new inbound message to a `closed` or `snoozed` conversation **reopens it to `open`**.

Received attachment bytes are retained up to `ATTACHMENT_MAX_BYTES` (default 10 MB) and are
individually fetchable. Message subject and body are indexed in **FTS5** for full-text search.

## REST API

| Method | Path                                      | Purpose                              |
| ------ | ----------------------------------------- | ------------------------------------ |
| `GET`  | `/v1/conversations`                       | List conversations                   |
| `GET`  | `/v1/conversations/:id`                   | Get one conversation plus its thread |
| `POST` | `/v1/conversations/:id/reply`             | Send a threaded reply                |
| `POST` | `/v1/conversations/:id/status`            | Update triage status                 |
| `POST` | `/v1/conversations/:id/assign`            | Assign or unassign                   |
| `POST` | `/v1/conversations/:id/tags`              | Add or remove tags                   |
| `POST` | `/v1/conversations/:id/read`              | Mark read                            |
| `GET`  | `/v1/messages/search`                     | Full-text search                     |
| `GET`  | `/v1/inbox/messages/:id/attachments/:idx` | Fetch an attachment's bytes          |

List filters include conversation age and unanswered state.

## MCP tools

| Tool                       | Purpose                                                                         |
| -------------------------- | ------------------------------------------------------------------------------- |
| `list_conversations`       | List and filter by status, assignee, tag, participant, unread, or query         |
| `get_conversation`         | Fetch one conversation plus its full chronological thread                       |
| `reply_to_conversation`    | Send a reply, auto-threading off the most recent inbound message                |
| `search_messages`          | Full-text search across inbound and outbound messages                           |
| `set_conversation_status`  | Set status to open/pending/closed/snoozed (`snooze_until` required for snoozed) |
| `assign_conversation`      | Assign or unassign a conversation to an agent                                   |
| `tag_conversation`         | Add and/or remove tags                                                          |
| `mark_conversation_read`   | Mark a conversation read                                                        |
| `mark_conversation_unread` | Mark a conversation unread                                                      |
| `fetch_attachment`         | Fetch one inbound attachment as base64 by message id and index                  |

A `triage_inbox` prompt is also served — see [MCP server](/stateset-mail/mcp-server#prompts).

## Mailboxes

Register addresses on a managed domain, e.g. `support@emails.stateset.com`. Incoming IMAP mail
whose `To:` or `Cc:` matches a registered address is routed to that mailbox
(`inbox.mailbox_id`).

When `MAIL_DOMAIN` is set, the send endpoint **requires** the `from` address on that domain to
be a registered mailbox.

Managed-domain onboarding is driven by these settings:

| Variable                                      | Default                    | Purpose                                                                       |
| --------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------- |
| `MAIL_DOMAIN`                                 | unset                      | Managed mailbox domain                                                        |
| `MAIL_MX_HOST`                                | `mx.<message-id domain>`   | Host customers point their MX record at                                       |
| `MAIL_SPF_INCLUDE`                            | `_spf.<message-id domain>` | SPF include customers add to their domain                                     |
| `MAIL_DMARC_RUA`                              | unset                      | Optional DMARC aggregate-report address surfaced in the suggested record      |
| `DNS_VERIFY_INTERVAL_SECS`                    | `60`                       | How often the worker re-checks unsettled managed domains                      |
| `STALWART_ADMIN_URL` / `STALWART_ADMIN_TOKEN` | unset                      | MTA admin API for auto-provisioning verified domains. Unset is a logged no-op |

## Webhooks

Conversation activity is carried on the standard webhook stream. `inbox.received` events
include the conversation, mailbox, domain, and tenant, plus attachment metadata; bounce events
carry the recipient. Subscriptions can be scoped to a tenant.

See [Configuration](/stateset-mail/configuration#webhooks) for subscription management.