@nocobase/app-plugin-mail 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/shared/participant.d.ts

@@ -0,0 +1,14 @@
+/** The participant index accepts ASCII dot-atom mailboxes and DNS domains. */
+export interface NormalizedMailParticipantAddress {
+    readonly address: string;
+    readonly domain: string;
+}
+export interface MailParticipantFilter {
+    readonly field: 'address' | 'domain';
+    readonly value: string;
+}
+/** Trim and lowercase without alias folding, truncation, or display-name parsing. */
+export declare function normalizeMailParticipantAddress(value: unknown): NormalizedMailParticipantAddress | undefined;
+/** An omitted filter is distinct from an explicitly empty or malformed one. */
+export declare function parseMailParticipant(value: string): MailParticipantFilter | undefined;
+//# sourceMappingURL=participant.d.ts.map

package/dist/shared/participant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"participant.d.ts","sourceRoot":"","sources":["../../shared/participant.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAkBD,qFAAqF;AACrF,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,gCAAgC,GAAG,SAAS,CAiB9C;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GACZ,qBAAqB,GAAG,SAAS,CAUnC"}

package/dist/shared/participant.js

@@ -0,0 +1,45 @@
+function normalizeDomain(value) {
+    const domain = value.toLowerCase();
+    if (domain.length > 253 || !domain.includes('.'))
+        return undefined;
+    const labels = domain.split('.');
+    if (labels.some((label) => label.length === 0 ||
+        label.length > 63 ||
+        !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)))
+        return undefined;
+    return domain;
+}
+/** Trim and lowercase without alias folding, truncation, or display-name parsing. */
+export function normalizeMailParticipantAddress(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (/[^\u0021-\u007e]/.test(value.trim()))
+        return undefined;
+    const address = value.trim().toLowerCase();
+    if (address.length > 320)
+        return undefined;
+    const at = address.indexOf('@');
+    if (at <= 0 || at !== address.lastIndexOf('@'))
+        return undefined;
+    const local = address.slice(0, at);
+    if (local.length > 64 ||
+        !/^[a-z0-9!#$%&'*+\-/=?^_`{|}~]+(?:\.[a-z0-9!#$%&'*+\-/=?^_`{|}~]+)*$/.test(local))
+        return undefined;
+    const domain = normalizeDomain(address.slice(at + 1));
+    return domain ? { address, domain } : undefined;
+}
+/** An omitted filter is distinct from an explicitly empty or malformed one. */
+export function parseMailParticipant(value) {
+    if (value.length > 320)
+        return undefined;
+    if (/[^\u0021-\u007e]/.test(value.trim()))
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized.startsWith('@')) {
+        const domain = normalizeDomain(normalized.slice(1));
+        return domain ? { field: 'domain', value: domain } : undefined;
+    }
+    const mailbox = normalizeMailParticipantAddress(normalized);
+    return mailbox ? { field: 'address', value: mailbox.address } : undefined;
+}
+//# sourceMappingURL=participant.js.map

package/dist/shared/participant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"participant.js","sourceRoot":"","sources":["../../shared/participant.ts"],"names":[],"mappings":"AAWA,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACnE,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IACE,MAAM,CAAC,IAAI,CACT,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,MAAM,KAAK,CAAC;QAClB,KAAK,CAAC,MAAM,GAAG,EAAE;QACjB,CAAC,mCAAmC,CAAC,IAAI,CAAC,KAAK,CAAC,CACnD;QAED,OAAO,SAAS,CAAC;IACnB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,+BAA+B,CAC7C,KAAc;IAEd,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3C,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnC,IACE,KAAK,CAAC,MAAM,GAAG,EAAE;QACjB,CAAC,qEAAqE,CAAC,IAAI,CACzE,KAAK,CACN;QAED,OAAO,SAAS,CAAC;IACnB,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAClC,KAAa;IAEb,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,CAAC;IACD,MAAM,OAAO,GAAG,+BAA+B,CAAC,UAAU,CAAC,CAAC;IAC5D,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5E,CAAC"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@nocobase/app-plugin-mail",
   "displayName": "Mail App Plugin",
   "description": "Provides mail sending and resumable mailbox synchronization architecture.",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "type": "module",
   "prettier": "@nocobase/dev-config/prettier",
   "engines": {
@@ -62,17 +62,17 @@
   "peerDependencies": {
     "@base-ui/react": "^1.6.0",
     "class-variance-authority": "^0.7.1",
+    "cn": "^0.4.0",
+    "date-fns": "^4.4.0",
     "lucide-react": "^0.487.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "date-fns": "^4.4.0",
     "react-day-picker": "^10.0.1",
-    "cn": "^0.4.0",
+    "react-dom": "^19.0.0",
     "@nocobase/app-client": "^3.0.0-beta.1",
-    "@nocobase/app-plugin-authentication": "^2.0.0-beta.7",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.9",
     "@nocobase/app-plugin-authorization": "^1.0.0-beta.27",
-    "@nocobase/app-server": "^2.0.0-beta.5",
-    "@nocobase/db": "^1.0.0-beta.19",
+    "@nocobase/app-server": "^2.0.0-beta.7",
+    "@nocobase/db": "^1.0.0-beta.20",
     "@nocobase/i18n": "^1.0.0-beta.7",
     "@nocobase/jobs": "^0.1.0-beta.3",
     "@nocobase/service-provider": "^0.0.2-beta.2"
@@ -86,8 +86,10 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
+    "@playwright/test": "^1.62.1",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.3",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^24.0.0",
     "@types/nodemailer": "^8.0.1",
@@ -104,10 +106,9 @@
     "tw-animate-css": "^1.2.5",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@playwright/test": "^1.62.1",
-    "@nocobase/dev-config": "0.1.0-beta.22",
-    "@nocobase/app-testing": "0.1.0-beta.3",
-    "@nocobase/config": "0.1.0-beta.3"
+    "@nocobase/app-testing": "0.1.0-beta.4",
+    "@nocobase/config": "0.1.0-beta.3",
+    "@nocobase/dev-config": "0.1.0-beta.22"
   },
   "repository": {
     "type": "git",

package/skills/nocobase-app-plugin-mail/SKILL.md

@@ -4,7 +4,7 @@ description: Use when integrating the NocoBase 3 Mail plugin into an application
 argument-hint: "[action: inspect|configure|integrate|send|diagnose] [target]"
 allowed-tools: Read, Grep, Glob, Bash
 owner: mail-plugin-team
-version: 1.1.2
+version: 1.2.0
 last-reviewed: 2026-09-26
 risk-level: medium
 ---
@@ -62,17 +62,19 @@ When the user says “you decide”, use `provider=auto`, `scope=local`, and `va
 
 # Reference Loading Map
 
-| Task                                                                                                                   | Read                                                                             |
-| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| Register Mail, configure provider quotas, connect an account, configure OAuth/push, or replace credential storage      | [Configuration and accounts](references/configuration-and-accounts.md)           |
-| Embed a production workspace, connect business records, customize reading/composition, or add management and log pages | [Client integration](references/client-integration.md)                           |
-| Send from business code, manage drafts or attachments, schedule or bulk-send, or handle uncertain delivery             | [Sending and drafts](references/sending-and-drafts.md)                           |
-| Set an initial sync boundary, handle Gmail quota errors, recover synchronization, or diagnose stalled tasks and logs   | [Synchronization and diagnostics](references/synchronization-and-diagnostics.md) |
+| Task                                                                                                                                                | Read                                                                             |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Register Mail, configure provider quotas, connect an account, configure OAuth/push, or replace credential storage                                   | [Configuration and accounts](references/configuration-and-accounts.md)           |
+| Embed a production workspace, connect business records, customize reading/composition, or add management and log pages                              | [Client integration](references/client-integration.md)                           |
+| Send from business code, manage drafts or attachments, schedule or bulk-send, or handle uncertain delivery                                          | [Sending and drafts](references/sending-and-drafts.md)                           |
+| Upgrade the participant index, set an initial sync boundary, handle Gmail quota errors, recover synchronization, or diagnose stalled tasks and logs | [Synchronization and diagnostics](references/synchronization-and-diagnostics.md) |
 
 # Safety Gate
 
 Do not expose credential values in logs, reports, screenshots, or test output. The default credential vault stores plain JSON in the database; promise encryption only when an application-supplied vault is configured.
 
+Participant-index upgrades require a backed-up maintenance window with application writes and Mail synchronization stopped; complete and verify the historical backfill before restarting or exposing filtered results. Bounded batches do not make this an online backfill. Read the [upgrade checklist](references/synchronization-and-diagnostics.md#participant-index-upgrade) before deployment.
+
 Treat `accepted` as provider acceptance, not recipient delivery; `unknown` may mean the provider already sent the message. Do not retry an uncertain submission until the sending reference and provider state have been checked.
 
 For destructive or external actions, keep the operation reversible where possible. If a configuration write is wrong, restore the read-back value from the prior snapshot and report the rollback. If a mailbox mutation is wrong, stop further mutations and use the provider's supported move, restore, or deletion-recovery operation; do not edit Mail tables directly. See Rollback Guidance below.

package/skills/nocobase-app-plugin-mail/references/client-integration.md

@@ -47,6 +47,24 @@ export function CustomerMail() {
 
 `{{record.customer.name}}` resolves when applying a template. Unknown variables stay visible. Applying a template replaces subject and body. This does not associate messages with a customer or filter correspondence automatically; implement explicitly requested record relationships in the application's domain layer.
 
+## CRM correspondence and participant filtering
+
+Use the application-owned client to load exact correspondence, independently of template variables:
+
+```ts
+const mail = app.services.resolve(mailClientToken);
+const customerMail = await mail.listMessages({
+  participant: 'alice@example.com',
+});
+const companyMail = await mail.listMessages({ participant: '@example.com' });
+```
+
+In React, obtain `mail` with `useMailClient()`. `participant` is optional in `MailMessagesQuery` and `MailManagedMessagesQuery` and is forwarded unchanged to the API. The server trims surrounding whitespace and lowercases the entire mailbox/domain before an exact From/To/Cc match. It accepts ASCII dot-atom mailboxes and dotted DNS domains, not display-name forms, quoted local parts or Unicode addresses. Domain input must start with `@`; `@example.com` excludes subdomains, similar domains and suffix tricks. There is no alias or `+tag` folding. Bcc, Reply-To, display names, subject, preview and body do not participate. `q` keeps its existing fuzzy behavior, including display names and Bcc, and intersects with participant and other filters. Results include only locally synchronized mail within the caller's existing account permissions; do not retry a denied personal request against management APIs.
+
+The workspace exposes a separate Participant field with full-address/`@domain` help and accessible validation errors. It uses the existing 300 ms keyword debounce interval, resets page tokens, list and reader selection immediately on every participant edit or clear, and ignores stale responses. Invalid input issues no list request. Clearing omits the parameter instead of sending an empty string. A custom CRM page must likewise clear tokens/selections, guard outstanding responses and block invalid filters; an explicit empty, invalid or oversized API value returns `400 INVALID_INPUT` with a `participant` field violation. `MailWorkspacePageProps` does not provide an externally controlled participant prop; own CRM filtering state in a custom page rather than assuming template variables set the filter.
+
+List totals and paging apply the filter before pagination; opening a conversation still loads the complete thread, and the conversation badge keeps its existing full-thread count. Separate IMAP folder copies are not deduplicated by this filter. Verify historical results only after the [participant index upgrade](synchronization-and-diagnostics.md#participant-index-upgrade) has completed.
+
 ## Build a custom mail page
 
 Use `useMailClient()` for typed data access and own page state in the application. `listMessages()` accepts `MAIL_VIRTUAL_FOLDER_IDS` for built-in cross-account folders; `getMessage()` or `listConversationMessages()` loads detail; mutation methods such as `updateMessage()`, `moveMessage()` and `sendMessage()` perform the corresponding server operation. A custom page can combine these calls with `MailMessageList`, `MailConversationView`, `MailboxSidebar` and `MailComposer`, or render its own UI. The application owns filtering, loading/error state, cursor handling, selected-message state and refreshing after the user-scoped realtime invalidation event.
@@ -191,7 +209,7 @@ Completion callbacks may return `void` or `Promise<void>`. Legacy callbacks that
 
 All-user detail and attachment APIs live under `/api/mail/management/accounts/:accountId/messages/:messageId`, with `/attachments/:attachmentId` for downloads. They require management permission. Opening management detail is read-only and does not mark mail read; draft rows use draft status and skip read-state actions. Moving to folders belongs to the personal workspace. Keep personal and all-user client paths explicit instead of retrying permission failures against a broader API.
 
-The Mail center pages by cursor, 50 messages per page: `listMessages()` and `listConversationMessages()` take `pageSize` and `pageToken`, and return `{ items, total, nextCursor }`, where `nextCursor` is the opaque token to send back as the next `pageToken` and is absent on the last page. Management and log tables page by number with page-size choices 20, 50 and 100: `listManagedMessages()`, `listSyncRunsPage()` and `listSubmissionsPage()` take `{ page, pageSize }` (page from 1, `pageSize` at most 100) and return `{ items, total }`. Reset pagination after filter or page-size changes. Search is `q`.
+The Mail center pages by cursor, 50 messages per page: `listMessages()` and `listConversationMessages()` take `pageSize` and `pageToken`, and return `{ items, total, nextCursor }`, where `nextCursor` is the opaque token to send back as the next `pageToken` and is absent on the last page. Management and log tables page by number with page-size choices 20, 50 and 100: `listManagedMessages()`, `listSyncRunsPage()` and `listSubmissionsPage()` take `{ page, pageSize }` (page from 1, `pageSize` at most 100) and return `{ items, total }`. Reset pagination and selection after filter or page-size changes. Keyword search is `q`; exact From/To/Cc filtering is the independent optional `participant`.
 
 Grouped bulk history counts complete batches, not recipients: call `listSubmissionsPage({ bulkOnly: true, groupByBatch: true, page, pageSize })`. Keep expandable recipient results inside their batch. Retry/cancel eligibility is defined in the sending reference.
 

package/skills/nocobase-app-plugin-mail/references/http-api.md

@@ -77,24 +77,32 @@ Mail publishes the user-scoped realtime topic `mail:messages` with `{ kind: 'mai
 
 ## Messages, conversations, attachments, and sending
 
-| Method   | Path                                                                 | Request / result                                                                                                                      |
-| -------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET`    | `/messages`                                                          | Filters by `accountId`, `folderId`, `labelId`, `conversationId`, `q`, `unread`, and `starred`; pages with `pageSize` and `pageToken`. |
-| `GET`    | `/messages/countUnread`                                              | Returns the current user's unread count as a number.                                                                                  |
-| `POST`   | `/messages/send`                                                     | Accepts `MailComposeInput`; returns `MailSubmissionView`.                                                                             |
-| `POST`   | `/messages/sendBulk`                                                 | Accepts `MailBulkComposeInput`; returns `MailSubmissionView[]`.                                                                       |
-| `POST`   | `/messages/saveDraft`                                                | Accepts draft compose fields; creates the draft or replaces the one named by `draftMessageId` or `draftKey`; returns `MailMessage`.   |
-| `GET`    | `/accounts/:accountId/conversations/:conversationId/messages`        | Conversation messages, paged with `pageSize` and `pageToken`.                                                                         |
-| `GET`    | `/accounts/:accountId/messages/:messageId`                           | Returns a `MailMessage`.                                                                                                              |
-| `PATCH`  | `/accounts/:accountId/messages/:messageId`                           | Optional read/starred/note/todo changes; returns the updated `MailMessage`.                                                           |
-| `DELETE` | `/accounts/:accountId/messages/:messageId`                           | Optional `permanently=true` query parameter; returns `204`.                                                                           |
-| `GET`    | `/accounts/:accountId/messages/:messageId/attachments/:attachmentId` | Streams a personal mailbox attachment.                                                                                                |
-| `POST`   | `/accounts/:accountId/messages/:messageId/modifyLabels`              | `addLabelIds` and/or `removeLabelIds`; returns the updated `MailMessage`.                                                             |
-| `POST`   | `/accounts/:accountId/messages/:messageId/move`                      | Requires `providerFolderId`; returns the updated `MailMessage`.                                                                       |
-| `POST`   | `/accounts/:accountId/messages/:messageId/retryContent`              | Retries deferred message content retrieval; returns the updated `MailMessage`.                                                        |
-| `POST`   | `/accounts/:accountId/messages/:messageId/resolveDraftConflict`      | Requires `action` `useRemote` or `keepLocal`; returns the resolved `MailMessage`.                                                     |
-| `POST`   | `/attachments`                                                       | `multipart/form-data` with field `file`, at most 27 MiB; returns `201` and `MailOutboundAttachmentView`.                              |
-| `GET`    | `/attachments/:attachmentId`                                         | Streams an uploaded outbound attachment.                                                                                              |
+| Method   | Path                                                                 | Request / result                                                                                                                                     |
+| -------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET`    | `/messages`                                                          | Filters by `accountId`, `folderId`, `labelId`, `conversationId`, `q`, `participant`, `unread`, and `starred`; pages with `pageSize` and `pageToken`. |
+| `GET`    | `/messages/countUnread`                                              | Returns the current user's unread count as a number.                                                                                                 |
+| `POST`   | `/messages/send`                                                     | Accepts `MailComposeInput`; returns `MailSubmissionView`.                                                                                            |
+| `POST`   | `/messages/sendBulk`                                                 | Accepts `MailBulkComposeInput`; returns `MailSubmissionView[]`.                                                                                      |
+| `POST`   | `/messages/saveDraft`                                                | Accepts draft compose fields; creates the draft or replaces the one named by `draftMessageId` or `draftKey`; returns `MailMessage`.                  |
+| `GET`    | `/accounts/:accountId/conversations/:conversationId/messages`        | Conversation messages, paged with `pageSize` and `pageToken`.                                                                                        |
+| `GET`    | `/accounts/:accountId/messages/:messageId`                           | Returns a `MailMessage`.                                                                                                                             |
+| `PATCH`  | `/accounts/:accountId/messages/:messageId`                           | Optional read/starred/note/todo changes; returns the updated `MailMessage`.                                                                          |
+| `DELETE` | `/accounts/:accountId/messages/:messageId`                           | Optional `permanently=true` query parameter; returns `204`.                                                                                          |
+| `GET`    | `/accounts/:accountId/messages/:messageId/attachments/:attachmentId` | Streams a personal mailbox attachment.                                                                                                               |
+| `POST`   | `/accounts/:accountId/messages/:messageId/modifyLabels`              | `addLabelIds` and/or `removeLabelIds`; returns the updated `MailMessage`.                                                                            |
+| `POST`   | `/accounts/:accountId/messages/:messageId/move`                      | Requires `providerFolderId`; returns the updated `MailMessage`.                                                                                      |
+| `POST`   | `/accounts/:accountId/messages/:messageId/retryContent`              | Retries deferred message content retrieval; returns the updated `MailMessage`.                                                                       |
+| `POST`   | `/accounts/:accountId/messages/:messageId/resolveDraftConflict`      | Requires `action` `useRemote` or `keepLocal`; returns the resolved `MailMessage`.                                                                    |
+| `POST`   | `/attachments`                                                       | `multipart/form-data` with field `file`, at most 27 MiB; returns `201` and `MailOutboundAttachmentView`.                                             |
+| `GET`    | `/attachments/:attachmentId`                                         | Streams an uploaded outbound attachment.                                                                                                             |
+
+### Participant query semantics
+
+`GET /messages` and `GET /management/messages` accept optional `participant` as a full mailbox (`alice@example.com`) or an exact domain (`@example.com`). The server trims leading/trailing whitespace and lowercases the whole mailbox/domain. Supported input is an ASCII dot-atom local part (at most 64 characters) with a dotted DNS domain (at most 253 characters, labels at most 63); the query value is at most 320 characters. Display-name forms, quoted local parts, Unicode addresses and malformed/empty values are rejected with `400 INVALID_ARGUMENT`, reason `INVALID_INPUT`, and a `participant` field violation. Permission is checked first. Omit the parameter to disable it.
+
+Only actual From, To and Cc addresses match. Subject, preview, body, display names, Bcc and Reply-To are excluded; aliases and `+tag` addresses are not folded. `@example.com` does not match `sub.example.com`, `notexample.com` or `example.com.evil`. Existing `q` fuzzy search is unchanged (including display names and Bcc) and intersects with participant and all other filters. Ownership, management permission, sort order and IMAP-copy record granularity are unchanged. The predicate applies before totals and pagination and never duplicates a matching message because several participants match. Searches cover locally synchronized mail only.
+
+Conversation-message detail and full-thread counts retain their existing semantics: a filtered list row can open a complete thread containing other participants. The internal participant index has no public CRUD endpoint. Existing installations must finish the [maintenance-window backfill](synchronization-and-diagnostics.md#participant-index-upgrade) before relying on historical filtered results.
 
 ## Synchronization and delivery history
 
@@ -111,12 +119,12 @@ Mail publishes the user-scoped realtime topic `mail:messages` with `{ kind: 'mai
 
 ## All-user management
 
-| Method | Path                                                                            | Request / result                                                                                    |
-| ------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `GET`  | `/management/messages`                                                          | Filters by `accountId`, `folderId`, `q`, `unread`, and `starred`; paged with `page` and `pageSize`. |
-| `POST` | `/management/messages/batchApply`                                               | Accepts `MailManagementMessageActionInput`; returns per-item results.                               |
-| `GET`  | `/management/accounts/:accountId/messages/:messageId`                           | Returns a read-only `MailMessage`; does not mark it read.                                           |
-| `GET`  | `/management/accounts/:accountId/messages/:messageId/attachments/:attachmentId` | Streams an all-user management attachment.                                                          |
+| Method | Path                                                                            | Request / result                                                                                                   |
+| ------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `GET`  | `/management/messages`                                                          | Filters by `accountId`, `folderId`, `q`, `participant`, `unread`, and `starred`; paged with `page` and `pageSize`. |
+| `POST` | `/management/messages/batchApply`                                               | Accepts `MailManagementMessageActionInput`; returns per-item results.                                              |
+| `GET`  | `/management/accounts/:accountId/messages/:messageId`                           | Returns a read-only `MailMessage`; does not mark it read.                                                          |
+| `GET`  | `/management/accounts/:accountId/messages/:messageId/attachments/:attachmentId` | Streams an all-user management attachment.                                                                         |
 
 ## OAuth and Provider webhooks
 

package/skills/nocobase-app-plugin-mail/references/public-api.md

@@ -84,6 +84,8 @@ Output status, folder-type and Provider error category/reason types have `Known.
 - **Synchronization:** `startSync`, `getSyncRun`, `listSyncRunsPage`, `retrySyncRun`, `cancelSyncRun`.
 - **Delivery history:** `listSubmissionsPage`, `retrySubmission`, `cancelSubmission`.
 
+`MailMessagesQuery` and `MailManagedMessagesQuery` include an optional `participant: string` for an exact normalized From/To/Cc mailbox or `@domain` match, independent of `q`. `MailClient` forwards it unchanged; omit it to clear the filter. List filtering does not trim full conversation details or change full-thread counts. See [CRM correspondence](client-integration.md#crm-correspondence-and-participant-filtering) for examples, validation and normalization boundaries.
+
 The TypeScript signatures are the request/result source of truth. For direct HTTP clients, see [HTTP API](http-api.md).
 
 ## Reusable components

package/skills/nocobase-app-plugin-mail/references/synchronization-and-diagnostics.md

@@ -8,6 +8,20 @@ Automatic synchronization is configured globally through `mail.automaticSyncInte
 
 `mail.syncBatchSize` or `MAIL_SYNC_BATCH_SIZE` defaults to 100, with an integer range of 1–200. This bounds each provider list page, not the total imported history. The account screen defaults a new initial sync to one calendar month ago. Direct account-creation APIs require `initialSyncReceivedAfter`; direct initial-sync requests must carry `receivedAfter` unless the account already has a saved start date. Both are RFC 3339 date-times such as `2026-01-01T00:00:00Z`. Legacy accounts without one use a one-month boundary for automatic or push-triggered first syncs. An active pre-upgrade initial run missing a valid boundary restarts with the same one-month fallback; Gmail rejects any initial list call without a valid date. The sync request no longer accepts `maxMessages`; an import is bounded only by its start date.
 
+## Participant index upgrade
+
+The participant feature adds an internal `mailMessageParticipants` collection and indexes, with one derived row per normalized From/To/Cc role/address. Historical data is backfilled from stored sender/recipient JSON, without provider requests or changes to original message JSON, timestamps, bodies or folders. Unsupported or invalid historical addresses/JSON are skipped with non-sensitive diagnostic counts; valid addresses from the same message remain eligible. Do not edit the index directly or treat partial backfill results as complete.
+
+Before production deployment, measure representative and large mailboxes: message and participant row counts, migration time, index storage, write overhead, locks and transaction-log usage. Large To/Cc sets increase participant rows and insertion cost. Keyset reads and bounded insert batches constrain memory and binding parameters, not total transaction duration or lock time; the migration is not an online backfill. If measurements do not fit a maintenance window, stop and plan a separately designed resumable task with completion and concurrency guarantees.
+
+1. With explicit production authorization, take and verify a restorable database backup and schedule the measured maintenance window.
+2. Stop application writes and all Mail/background sync workers, including other processes sharing the database; do not run the old version concurrently with backfill.
+3. Deploy the upgraded artifacts and run the application's migration command (`pnpm nocobase db apply` in a source application, or `node dist/cli/index.js db apply` in a deployment). This applies the schema and historical backfill together.
+4. Verify successful migration completion, inspect non-sensitive skip counts, and check known historical From/To/Cc full-address and `@domain` queries, exclusions, totals and pagination. Verify original messages are intact before enabling traffic.
+5. Only then restart the upgraded application and sync workers and verify newly synchronized messages appear in participant queries.
+
+On failure, leave writes and synchronization stopped, inspect the migration error and transaction outcome, and use the application's migration recovery procedures or the verified backup before retrying. Never expose a partly populated index or repair data by editing Mail tables. A migration rollback removes only the derived participant structure; original sender/recipient JSON remains available for a later reapply/backfill. Rehearse apply/rollback/reapply and failure recovery on a database copy before the production window.
+
 ## Gmail quota, HTTP batch, and retry behavior
 
 For Gmail, one list page is fetched with `messages.list`, followed by one `messages.get` per message. Mail groups up to 10 message gets into each HTTP `multipart/mixed` batch request. Batching reduces HTTP connections only: Google charges every embedded call separately, so `messages.get` still costs 20 quota units and `messages.list` costs 5. A 100-message page therefore costs about 2,005 units before incidental profile, label, history, or fallback metadata calls; it does not become a single quota unit. See [Gmail quota configuration](configuration-and-accounts.md#gmail-quota-configuration) for defaults and project overrides.