@nocobase/app-plugin-mail 0.0.0-stage → 1.0.0-beta.8

package/skills/nocobase-app-plugin-mail/references/configuration-and-accounts.md

@@ -0,0 +1,167 @@
+# Configuration and accounts
+
+## Contents
+
+- [Registration and configuration ownership](#registration-and-configuration-ownership)
+- [Connect and manage accounts](#connect-and-manage-accounts)
+- [OAuth callback and return page](#oauth-callback-and-return-page)
+- [Push synchronization](#push-synchronization)
+- [IMAP/SMTP boundaries and sent copies](#imapsmtp-boundaries-and-sent-copies)
+- [Credential storage and provider extensions](#credential-storage-and-provider-extensions)
+- [Verify this path](#verify-this-path)
+
+## Registration and configuration ownership
+
+Inspect the application's Client, Server, and configuration composition roots before adding Mail. `pnpm nocobase plugin register mail` installs the package, wires Client/Server composition entries, and synchronizes this Skill, but it does not register the application-owned `mail` configuration. Add `server/config/mail.ts`, import it from `server/config/index.ts`, and complete the required migrations through the application's migration workflow. Configuration and credential work alone do not require creating another plugin or another migration. Background synchronization and scheduled sending require the application jobs service: `JobExecutorServiceProvider` from `@nocobase/app-server/jobs` in `server/app.ts`, which the application templates already compose. Mail runs them on its `@nocobase/app-plugin-mail` scope. `mail.jobs` (override `MAIL_JOBS`) names the `jobs` configuration they run on, for example one with its own `concurrency`; left out, they follow `jobs.default`, and a name that `jobs` does not define stops the application from starting. The memory adapter serves one process, so an application running more than one instance needs a `redis` jobs configuration.
+
+Use this minimal configuration registration in an application that does not already provide it:
+
+```ts
+// server/config/mail.ts
+import { mailConfig } from '@nocobase/app-plugin-mail/server';
+
+export default mailConfig;
+```
+
+Then add `import mail from './mail.js';`, `mail: ReturnType<typeof mail>;`, and `mail,` to `server/config/index.ts` alongside the existing application config factories. The Mail plugin falls back to built-in defaults when the whole namespace is absent, but provider instances still require this registration. If the application uses `MAIL_*` environment overrides, merge `mailEnvironmentMappings` from `@nocobase/app-plugin-mail/server` into its mappings in `server/environment.ts`; package metadata lists supported variables but does not activate them. The OAuth overrides are `MAIL_OAUTH_CALLBACK_URL` and `MAIL_OAUTH_RETURN_URL`.
+
+`mail.providers` is a map keyed by stable instance names. The map key is the provider name; each value contains `type` and provider-specific options. Multiple instances of the same type can coexist. Renaming an instance breaks its existing account association. `enabled` defaults to `true`; disabling an instance also makes it unavailable to existing accounts.
+
+Keep only the instances needed by the application. These placeholders describe the configuration shape; replace them before connecting an account. User mailbox providers are separate from SMTP providers under `notification` used for system notifications.
+
+```yaml
+mail:
+  providers:
+    google:
+      type: gmail
+      clientId: replace-with-google-oauth-client-id
+      clientSecret: replace-with-google-oauth-client-secret
+      # Optional. Set to the quota allocated to this Google Cloud project.
+      quota:
+        projectId: replace-with-google-cloud-project-id
+        unitsPerUserPerMinute: 6000
+        unitsPerProjectPerMinute: 1200000
+    microsoft-365:
+      type: microsoft
+      clientId: replace-with-microsoft-entra-client-id
+      clientSecret: replace-with-microsoft-entra-client-secret
+      # tenant: common # Default; override for a specific tenant.
+    company-mail:
+      type: imap-smtp
+      imap:
+        host: imap.example.com
+        port: 993
+        secure: true
+      smtp:
+        host: smtp.example.com
+        port: 465
+        secure: true
+      # Enable only when the SMTP service does not save sent messages itself.
+      # sentCopyMode: client
+      # sentFolder: Sent # Existing folder; optional if the server marks a Sent folder.
+```
+
+Use one of the following instance shapes; inspect the installed provider types for optional settings rather than copying internal adapter code.
+
+| Type        | Required configuration and connection                                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `gmail`     | `clientId`, `clientSecret`; connect through Google OAuth                                                                              |
+| `microsoft` | `clientId`, `clientSecret`; optional `tenant` defaults to `common`; connect through Microsoft OAuth                                   |
+| `imap-smtp` | `imap` and `smtp`, each with `host`, `port`, and `secure`; the user supplies mailbox address, username and password during connection |
+
+## Gmail quota configuration
+
+`quota` is an optional server-side setting on each Gmail provider instance; it is not an end-user setting. Both values are positive integer quota units per minute. When omitted, Mail uses 6,000 units per user per project per minute and 1,200,000 units per project per minute, then paces requests at 80% of those limits. These are the current default limits for newer Google Cloud projects; actual allocations can differ, especially for older or quota-adjusted projects. Check the Gmail API quota page and the project's Google Cloud Console before raising a value. A local override does not request or increase Google's quota.
+
+The limiter keys project usage by `quota.projectId` (or falls back to OAuth `clientId`) and user usage by that project ID plus mailbox address. Set the same Google Cloud project ID on provider instances that use different OAuth client IDs from one project, so their quotas are coordinated in-process. The limiter is in-memory per application process. When multiple server processes share the same Gmail project, divide the project's actual per-user and per-project limits among those processes (or route Gmail sync through one worker); repeating the full project quota on every process can exceed Google's shared quota.
+
+```yaml
+mail:
+  providers:
+    google:
+      type: gmail
+      clientId: replace-with-google-oauth-client-id
+      clientSecret: replace-with-google-oauth-client-secret
+      quota:
+        projectId: replace-with-google-cloud-project-id
+        unitsPerUserPerMinute: 6000 # Replace with the actual allocation when it differs.
+        unitsPerProjectPerMinute: 1200000
+```
+
+Use the un-throttled Google quota values in configuration; Mail applies its 20% headroom internally. Omit either property to use the corresponding default. The defaults are intentionally conservative and may slow projects with higher approved quotas.
+
+Official references: [Gmail API quotas and quota-increase guidance](https://developers.google.com/workspace/gmail/api/reference/quota?hl=zh-cn). [verified: 2026-09-26]
+
+For IMAP/SMTP, `secure: true` means TLS from connection start; STARTTLS endpoints use the service's prescribed settings. TLS certificate verification defaults to enabled. Mail validates both endpoints before saving account credentials. Use the provider-required app password or authorization code where applicable.
+
+Provider secrets, endpoints and allowed OAuth `scopes` live in `mail.providers`. The top-level `MAIL_*` overrides below do not create per-provider credential environment mappings. Do not assume generic `${NAME}` interpolation in YAML; use the target application's supported server configuration mechanism. In applications generated from the OSS default template, merge `mailEnvironmentMappings` into the application-owned mappings in `server/environment.ts`. Keep actual secrets in private server configuration, out of committed examples and client bundles, and restart after changing configuration.
+
+## Connect and manage accounts
+
+Development account setup is at `/dev/mail/accounts`, relative to the application's public base path. It contains account connection, a history start date defaulting to one calendar month ago, account suspend/resume and removal, and signature, template and NocoBase label management. New OAuth and credential-based account requests must include `initialSyncReceivedAfter` as a valid ISO 8601 date-time; the server rejects a missing or invalid boundary instead of allowing an unbounded initial import. A registered provider without a configured instance is unavailable for connection.
+
+Use public account and authorization APIs or the existing client flow. OAuth starts with an authenticated request to `POST /api/mail/authorizations`; credential-based connection uses `POST /api/mail/accounts/connect`. Preserve the plugin's short-lived, single-use OAuth state. Account and log responses must remain free of credentials and tokens.
+
+Personal account operations use `/api/mail/accounts`. `/settings/mail/accounts` is a read-only overview backed by `/api/mail/settings/accounts`, with owner names and a user-ID fallback. Suspending prevents sending and synchronization. Removing an account clears its local data and authorization without deleting provider mailbox messages; remote subscription cleanup can fail without preventing local removal.
+
+## OAuth callback and return page
+
+The default callback is the app-local `/mail/oauth/callback`. Mail combines `app.publicOrigin` (or the request origin) with `app.publicBasePath` and that path. An application mounted at `/main` with origin `https://mail.example.com` uses:
+
+```text
+https://mail.example.com/main/mail/oauth/callback
+```
+
+Override through `mail.oauthCallbackUrl` or `MAIL_OAUTH_CALLBACK_URL`. A relative path receives the application prefix; an absolute HTTP(S) URL must already include it and reach the mounted callback. Register the exact resulting URL with the OAuth provider. Fragments are invalid. `oauthCallbackUrl` controls only the provider callback endpoint, not the page shown in the browser after authorization.
+
+Configure the browser destination through `mail.oauthReturnUrl` or `MAIL_OAUTH_RETURN_URL`. It defaults to `/dev/mail/accounts` for backward compatibility. A relative return path receives the application public base path, so `/mail/accounts` under `/main` becomes `/main/mail/accounts`; an absolute HTTP(S) URL is also supported and is treated as trusted server configuration. Fragments are invalid.
+
+For a production application, configure the callback and return paths together so the provider callback and application page are not confused:
+
+```yaml
+mail:
+  oauthCallbackUrl: /mail/oauth/callback
+  oauthReturnUrl: /mail/accounts
+```
+
+With origin `https://mail.example.com` and public base path `/main`, the provider must redirect to `https://mail.example.com/main/mail/oauth/callback`, and the browser will finish at `https://mail.example.com/main/mail/accounts?mailAuthorization=success` or `https://mail.example.com/main/mail/accounts?mailAuthorization=failure`. Register the full callback URL with the selected OAuth provider, such as Google for Gmail or Microsoft Entra ID for Microsoft 365, not the return page URL.
+
+When deployment values come from environment variables, use `MAIL_OAUTH_CALLBACK_URL=/mail/oauth/callback` and `MAIL_OAUTH_RETURN_URL=/mail/accounts` as the values and explicitly map them to `mail.oauthCallbackUrl` and `mail.oauthReturnUrl` in the application's `server/environment.ts`. Declaring the variables in the Mail package metadata does not replace the application's mapping, and generic `${NAME}` interpolation must not be assumed.
+
+The plugin preserves query parameters already present in the configured return URL and adds or replaces `mailAuthorization=success` or `mailAuthorization=failure`. The application-owned return page can use this status to show a result and refresh its account state.
+
+The callback route still performs provider code exchange, OAuth state validation, and account persistence before redirecting. A custom return page therefore does not implement the OAuth callback and does not call `POST /api/mail/accounts/connect` to save the just-authorized account again. If the page also exposes a new-account action, it may compose `MailAccountConnector` or call the documented authorization APIs for that separate action.
+
+The browser flow is: the provider redirects to `oauthCallbackUrl`; Mail validates the one-time state, completes authorization and saves the account; Mail redirects to `oauthReturnUrl`; the application-owned page reads `mailAuthorization` and refreshes `GET /api/mail/accounts` if needed. A missing `state` is rejected with HTTP 400 and does not redirect to the return page.
+
+Before enabling production account connection, confirm that the application-owned return route exists in the production client, the full callback URL is registered with the provider, the configured relative paths match the public base path, and both success and failure destinations are handled.
+
+## Push synchronization
+
+Push is optional and supplements periodic synchronization. Configure both `mail.pushWebhookUrl` and `mail.pushWebhookSecret`, or their overrides `MAIL_PUSH_WEBHOOK_URL` and `MAIL_PUSH_WEBHOOK_SECRET`. The base URL must reach the public Mail webhook route; the secret is 32–128 characters using letters, digits, `_`, or `-`.
+
+For example, base `https://mail.example.com/main/mail/webhooks`, type `gmail`, and instance `google` produce `https://mail.example.com/main/mail/webhooks/gmail/google/<secret>`.
+
+- Gmail also needs `pushTopicName` and a Pub/Sub push subscription targeting the complete URL. The topic must allow Gmail's push service to publish. Optional `pushLabelIds` narrows the watch; Mail creates and renews account watches.
+- Microsoft Graph subscriptions, endpoint validation, `clientState` checks and renewal are handled by Mail. The endpoint must be publicly reachable over HTTPS.
+- IMAP/SMTP has no push support.
+
+Preserve webhook secret validation and the provider-specific boundary; external webhook callers have no application session. A notification schedules the existing incremental path rather than writing messages directly. Keep periodic sync enabled as the fallback.
+
+## IMAP/SMTP boundaries and sent copies
+
+The generic adapter supports periodic new-UID discovery, sending, attachments, read/star updates and explicit permanent deletion. It does not support remote draft mirrors, discovered aliases, provider-native labels, move-to-folder, or complete external flag/deletion/move reconciliation. Local drafts and NocoBase metadata remain supported. Ordinary deletion is rejected because this adapter cannot move mail to Trash; do not substitute permanent deletion for that action.
+
+`sentCopyMode` defaults to `server`, leaving sent-mail archiving to SMTP. When the service does not save sent copies, set `sentCopyMode: client` and use an existing `sentFolder` or server-designated Sent folder. The plugin appends the sent content and checks Message-ID before append. Keep `server` when the service saves asynchronously: an immediate duplicate check cannot see a future server copy.
+
+A failed append records `IMAP_SENT_COPY_FAILED` while retaining the accepted submission. Fix the archive configuration without resending the accepted mail. The client does not automatically retry an ambiguous append. Advanced folder hints `sentFolder`, `trashFolder`, and `draftsFolder` identify provider folders; they do not enable unsupported move or remote-draft capabilities. Keep `trashFolder` and `draftsFolder` out of the minimal configuration example. Setting `sentFolder` alone does not enable client archiving; `sentCopyMode: client` is required.
+
+## Credential storage and provider extensions
+
+The default `mailCredentialVaultToken` implementation persists plain JSON. For encryption, register a compatible replacement before Mail Core and verify save, load, token rotation, and removal through account operations. Preserve ownership checks and API redaction; encryption does not replace either.
+
+Third-party provider definitions register through `mailProviderRegistryToken`. For a requested extension, inspect the installed `MailProviderDefinition` and `MailProviderAdapter` types and the package's shipped provider documentation. Implement the capabilities actually advertised, including resumable page and cursor contracts where synchronization is supported. Built-in provider configuration alone needs no extension.
+
+## Verify this path
+
+Confirm registration, migrations, provider availability, and connection with the intended account. Check that the account API returns no token material, an unrelated user cannot operate it, and disabling it blocks send/sync. For OAuth changes, verify exact callback matching, rejection of reused state, account persistence before redirect, configured destinations under the actual application base path, preservation of existing query parameters, and the destination after both success and failure. For push changes, verify the generated endpoint and an actual sync trigger separately from periodic polling.

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

@@ -0,0 +1,131 @@
+# Mail HTTP API
+
+## Contract and access
+
+The authenticated API base is `/api/mail`, the plugin's namespace; every resource (accounts, messages, labels, templates, sync runs, submissions) lives under it. Paths are camelCase, and custom methods are `POST /{collection}/{id}/{verb}` or `POST /{collection}/{verb}`. Successful JSON responses use `{ data }`; a list is `{ data: [...], meta }`. Creates return `201`, deletes return `204` with an empty body, and attachment reads return a byte stream. Prefer `MailClient` from `@nocobase/app-plugin-mail/client` so callers share the package's request types, path encoding, and paging.
+
+The running application documents every `/api/mail` route — parameters, bodies, response schemas, and error statuses — in its OpenAPI document: Swagger UI at `/api/swagger/docs` and the JSON at `/api/swagger`, readable with a signed-in session or an API key. Each route is tagged `Mail` and has an operationId of the form `mail<Verb><Resource>`, such as `mailSendMessage`. Treat that document as the reference for exact shapes; this page explains behavior it cannot.
+
+Every route under `/api/mail` requires an authenticated user and access to a Mail page resource, checked before input is validated or any record is read. Routes under `/settings` require `mail.admin`; routes under `/management` require `mail.management`; all other routes require `mail.workspace`. Personal account and message operations enforce account ownership. Management message reads are read-only.
+
+Lists page one of two ways. Feeds (`/messages` and conversation messages) take `pageSize` and `pageToken` and answer `meta: { nextPageToken, total }`; `nextPageToken` is absent on the last page and is sent back unchanged as `pageToken`. Log and management tables (`/syncRuns`, `/submissions`, `/settings/syncRuns`, `/settings/submissions`, `/management/messages`) take `page` and `pageSize` and answer `meta: { page, pageSize, total }`. `pageSize` defaults to 20 and is at most 100. Search is `q`. Bounded lists — Providers, accounts, identities, signatures, folders, labels, templates, and the admin and management account overviews — are answered whole as `{ data, meta: { total } }`. Dates in requests, such as `initialSyncReceivedAfter`, `receivedAfter`, and `scheduledAt`, are RFC 3339 date-times.
+
+Every JSON body is validated strictly: an unknown or invalid field is `400 INVALID_ARGUMENT` with reason `INVALID_INPUT` (domain `app`) and a `fieldViolations` entry per problem. A `PATCH` changes only the fields it sends; an omitted field keeps its stored value.
+
+## Errors
+
+Failures use the standard body `{ error: { code, status, reason, domain, message, localizedMessage?, fieldViolations?, metadata?, requestId } }`. Mail's errors use domain `mail`; branch on `reason`, never on `message`, which is English developer text. `localizedMessage` carries the text translated for the request's locale, which `mailErrorMessage(cause, fallback)` shows.
+
+| HTTP | `status`              | `reason`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 400  | `INVALID_ARGUMENT`    | `INVALID_MAIL_REQUEST` for input Mail rejects below the schema, such as an invalid page token or a missing upload `file`; `MAIL_ACCOUNT_CREDENTIALS_INVALID` when the Provider refuses the sign-in while connecting an account, with a field violation on `password`; a resource the body refers to that is missing, with `fieldViolations` naming the field: `MAIL_ACCOUNT_NOT_FOUND`, `MAIL_IDENTITY_NOT_FOUND`, …                                                                                         |
+| 400  | `FAILED_PRECONDITION` | `MAIL_ACCOUNT_INACTIVE`, `MAIL_ACCOUNT_REMOVING`, `MAIL_DRAFT_SCHEDULED`, `MAIL_SYNC_RUN_STATE_INVALID`, `MAIL_SUBMISSION_STATE_INVALID`, `MAIL_PROVIDER_UNAVAILABLE`, `MAIL_PROVIDER_OPERATION_UNSUPPORTED`, …; `MAIL_ACCOUNT_REAUTHORIZATION_REQUIRED` when the Provider no longer accepts the account's authorization (revoked or expired) and the user must reconnect it; `MAIL_PROVIDER_REQUEST_FAILED` when the Provider refused the request itself, such as a recipient or content it does not accept |
+| 403  | `PERMISSION_DENIED`   | `MAIL_ACCESS_DENIED`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| 404  | `NOT_FOUND`           | The resource the URL names: `MAIL_ACCOUNT_NOT_FOUND`, `MAIL_MESSAGE_NOT_FOUND`, `MAIL_SYNC_RUN_NOT_FOUND`, `MAIL_SUBMISSION_NOT_FOUND`, `MAIL_LABEL_NOT_FOUND`, `MAIL_TEMPLATE_NOT_FOUND`, `MAIL_SIGNATURE_NOT_FOUND`, `MAIL_ATTACHMENT_NOT_FOUND`, …                                                                                                                                                                                                                                                        |
+| 409  | `ALREADY_EXISTS`      | `MAIL_LABEL_ALREADY_EXISTS`, `MAIL_ACCOUNT_ALREADY_CONNECTED`                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| 409  | `ABORTED`             | `MAIL_IDEMPOTENCY_CONFLICT`, `MAIL_DRAFT_REVISION_OUTDATED`                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| 413  | `INVALID_ARGUMENT`    | `BODY_TOO_LARGE`: a JSON body over 8 MiB or an upload over 27 MiB                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| 415  | `INVALID_ARGUMENT`    | `INVALID_MAIL_REQUEST`: an upload that is not `multipart/form-data`                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| 429  | `RESOURCE_EXHAUSTED`  | `MAIL_PROVIDER_REQUEST_FAILED` when the Provider throttles the request or a Provider quota ran out; when the Provider says how long to wait, `Retry-After` and `metadata.retryAfter` give the delay in seconds                                                                                                                                                                                                                                                                                               |
+| 503  | `UNAVAILABLE`         | `MAIL_PROVIDER_REQUEST_FAILED` when the Provider is unreachable, times out or fails on its side, such as an HTTP 5xx or a transient SMTP reply; `Retry-After` is set when the Provider gave a delay                                                                                                                                                                                                                                                                                                          |
+
+Only a route that waits for the Provider while answering can return the Provider statuses: connecting an account, changing read or starred state, moving or deleting a message, retrying message content, and downloading a Provider attachment. Sending, saving drafts and synchronization reach the Provider in the background or record its failure on the submission or sync run (`error` with `code`, `category`, `retryable`), so they never answer `429` or `503`. Every Provider error carries the public Provider error in `metadata` (`code`, `category`, `retryable`, `retryAfterMs` and an allowlisted `reasonCode` when known), never the Provider's own message.
+
+An unexpected failure is `500 INTERNAL` and reveals nothing about its cause.
+
+Request and response types use the names exported from `@nocobase/app-plugin-mail/server` and `@nocobase/app-plugin-mail/client`. New response fields are optional, and callers should ignore fields they do not use. Account, folder, sync, submission, Provider error category/reason, and realtime event values may be unknown to an older client; keep a fallback for those values.
+
+Mail publishes the user-scoped realtime topic `mail:messages` with `{ kind: 'mail.changed' }` as an invalidation signal; it contains no message content. Subscribe through the host Realtime client and refresh affected data after the event or a reconnect. The Client package exports `MAIL_REALTIME_TOPIC` and `MailRealtimeEvent` from its client entry and the `realtime` subpath.
+
+## Providers and accounts
+
+| Method   | Path                                      | Request / result                                                                                                                                                                                                         |
+| -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GET`    | `/providers`                              | Returns `MailProviderView[]`.                                                                                                                                                                                            |
+| `POST`   | `/authorizations`                         | Provider `type` and `name`, optional `scopes`, and required `initialSyncReceivedAfter`; returns `201` and `MailAuthorizationStartResult`.                                                                                |
+| `POST`   | `/accounts/connect`                       | Provider `type` and `name`, `address`, optional `displayName`, `username`, required `password`, and required `initialSyncReceivedAfter`; verifies the credentials, then returns `201` and the created `MailAccountView`. |
+| `GET`    | `/accounts`                               | Returns the current user's `MailAccountView[]`.                                                                                                                                                                          |
+| `PATCH`  | `/accounts/:accountId`                    | Optional `status` (`active` or `suspended`); returns the updated `MailAccountView`.                                                                                                                                      |
+| `DELETE` | `/accounts/:accountId`                    | Starts the asynchronous, durable account removal; returns `202` with the account in its `removing` status, or `202` with no body when the removal already finished.                                                      |
+| `GET`    | `/settings/accounts`                      | Admin overview (`mail.admin`); returns `MailManagedAccountView[]`.                                                                                                                                                       |
+| `GET`    | `/settings/syncRuns`                      | Admin view of every user's sync runs, newest first, paged with `page` and `pageSize`; `canManage` marks the caller's own.                                                                                                |
+| `GET`    | `/settings/submissions`                   | Admin view of every user's submissions, newest first, paged with `page` and `pageSize`.                                                                                                                                  |
+| `GET`    | `/management/accounts`                    | Management overview (`mail.management`); returns `MailManagedAccountView[]`.                                                                                                                                             |
+| `GET`    | `/management/accounts/:accountId/folders` | Returns folders for the selected account; `404 MAIL_ACCOUNT_NOT_FOUND` when the account does not exist.                                                                                                                  |
+
+`/settings/accounts` and `/management/accounts` return the same list for two different pages, each gated by its own page permission.
+
+## Identities, signatures, labels, and templates
+
+| Method   | Path                                           | Request / result                                                                        |
+| -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `GET`    | `/accounts/:accountId/identities`              | Returns `MailIdentity[]`.                                                               |
+| `PATCH`  | `/accounts/:accountId/identities/:identityId`  | Optional `displayName`; returns the updated `MailIdentity`.                             |
+| `GET`    | `/accounts/:accountId/signatures`              | Returns `MailSignature[]`.                                                              |
+| `POST`   | `/accounts/:accountId/signatures`              | Creates a signature from name, text/html content, and default selection; returns `201`. |
+| `PATCH`  | `/accounts/:accountId/signatures/:signatureId` | Updates the sent fields of a signature (`name`, `text`, `html`, `isDefault`).           |
+| `DELETE` | `/accounts/:accountId/signatures/:signatureId` | Deletes a signature; returns `204`.                                                     |
+| `GET`    | `/accounts/:accountId/folders`                 | Returns the current user's folders for the account.                                     |
+| `GET`    | `/labels`                                      | Returns the current user's labels.                                                      |
+| `POST`   | `/labels`                                      | Creates a label from `MailSaveLabelInput`; returns `201`.                               |
+| `PATCH`  | `/labels/:labelId`                             | Updates the sent fields of a label (`name`, `color`).                                   |
+| `DELETE` | `/labels/:labelId`                             | Deletes a label; returns `204`.                                                         |
+| `GET`    | `/templates`                                   | Returns the current user's `MailTemplate[]`.                                            |
+| `POST`   | `/templates`                                   | Creates a template from `MailSaveTemplateInput`; returns `201`.                         |
+| `PATCH`  | `/templates/:templateId`                       | Updates the sent fields of a template (`name`, `subject`, `text`, `html`).              |
+| `DELETE` | `/templates/:templateId`                       | Deletes a template; returns `204`.                                                      |
+
+## 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.                                                                                              |
+
+## Synchronization and delivery history
+
+| Method | Path                                | Request / result                                                                                                        |
+| ------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `POST` | `/accounts/:accountId/sync`         | Accepts optional `mode` and `receivedAfter`; returns `202` and `MailSyncRunView`.                                       |
+| `GET`  | `/syncRuns`                         | The current user's sync runs, paged with `page` and `pageSize`.                                                         |
+| `GET`  | `/syncRuns/:syncRunId`              | Returns one `MailSyncRunView`.                                                                                          |
+| `POST` | `/syncRuns/:syncRunId/retry`        | Queues a retry; returns `202` and the updated run.                                                                      |
+| `POST` | `/syncRuns/:syncRunId/cancel`       | Cancels a run; returns the updated run.                                                                                 |
+| `GET`  | `/submissions`                      | Paged with `page` and `pageSize`; filters with `bulkOnly` and `groupByBatch`. Grouped bulk results count whole batches. |
+| `POST` | `/submissions/:submissionId/retry`  | Retries an eligible submission; returns `MailSubmissionLogView`.                                                        |
+| `POST` | `/submissions/:submissionId/cancel` | Cancels an eligible submission; returns `MailSubmissionLogView`.                                                        |
+
+## 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.                                                          |
+
+## OAuth and Provider webhooks
+
+These two are root routes outside `/api`, so they answer what their protocol requires rather than the API body above, and the OpenAPI document does not list them.
+
+OAuth uses the configured callback path, defaulting to `/mail/oauth/callback`. It requires a short-lived, single-use `state` returned by `POST /api/mail/authorizations`; successful and failed callbacks redirect to the configured `mail.oauthReturnUrl` with `mailAuthorization=success` or `mailAuthorization=failure`.
+
+Provider push notifications use `POST /mail/webhooks/:providerType/:providerName/:secret`. The URL secret and Provider client state are validated by the plugin; webhook request bodies are limited to 1,000,000 bytes.
+
+## Compatibility
+
+Within a major version, existing methods, paths, request requirements, response meanings, error reasons, permission resources, and stream behavior remain stable. Additive request fields are optional; additive response fields are optional. A required-field addition, path removal, behavior change, or permission change requires a new major version and a migration note.

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

@@ -0,0 +1,117 @@
+# Mail public API
+
+## Package entries
+
+| Entry                                         | Purpose                                                                                                                     |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `@nocobase/app-plugin-mail/server`            | Server plugin, application configuration, Server service token and Provider extension contracts.                            |
+| `@nocobase/app-plugin-mail/client`            | Client plugin, `MailClient`, its application token/hook, `MailWorkspacePage`, template helpers and realtime event contract. |
+| `@nocobase/app-plugin-mail/client/components` | Curated Mail UI components and their props/state types.                                                                     |
+| `@nocobase/app-plugin-mail/realtime`          | Realtime topic and event type for consumers that only need the event contract.                                              |
+| `@nocobase/app-plugin-mail/package.json`      | Package metadata.                                                                                                           |
+
+The package root is a Server alias retained for plugin registration and application configuration. Use the explicit `/server` entry in new application code. Package export maps are the public boundary; source files such as `server/tokens`, `server/types`, `client/plugin`, `client/routes`, and the internal component barrel are not public imports.
+
+## Server entry
+
+### Plugin and configuration
+
+The Server entry exports the default plugin, `mailConfig`, `DEFAULT_MAIL_CONFIG`, `mailEnvironmentMappings`, `resolveMailConfig`, and the `MailConfig`/provider configuration types. Applications register the plugin and explicitly compose its configuration factory as described in [Configuration and accounts](configuration-and-accounts.md).
+
+### Supported tokens
+
+- `mailServiceToken` resolves `MailService`, the consumer-facing facade for account, mailbox, message, label, signature, template, synchronization and delivery operations. Application plugins consume this service; they do not implement it.
+- `mailProviderRegistryToken` resolves `MailProviderRegistry`. A Server plugin registers a `MailProviderDefinition` during boot.
+- `mailCredentialVaultToken` resolves `MailCredentialVault`. Replace it only before Mail Core initializes, when the application owns an alternative credential store.
+- `createMailProviderRegistry()` creates an isolated registry, primarily for tests and standalone integrations. Application plugins should register with the Mail Core registry token instead of replacing it.
+
+Internal persistence, runtime, adapter-resolver and outbound-storage tokens are intentionally excluded.
+
+### Provider extension contract
+
+Use `defineMailProviderDefinition()` to type-check a `MailProviderDefinition<TConfig>`. Its stable extension points are:
+
+- `type`, `label`, optional `validateConfig`, and extensible `capabilities` metadata.
+- Optional `authorization`, `connection`, and `push` handlers.
+- Required `createAdapter(context, config, account)`, returning a `MailProviderAdapter` for folder/message listing, content and attachment reads, sends, drafts, message mutations, and optional push subscription operations. The `MailProviderAccount` argument exposes only the account ID, address, Provider identity, and opaque credential reference; retrieve credentials through `context.credentials`.
+- `MailProviderContext` provides the public base path and the credential vault. The vault supports `put`, `get`, `replace`, `getOrRefresh`, `delete`, and optionally `deleteExpired`. Authorization secrets belong in that vault, not in account records or logs.
+
+Associated request/result contracts are exported for authorization, connection, change/folder/message pagination, normalized mail records, sending, push notifications and credential access. Advertise only the capabilities supported by the returned adapter; Mail checks capabilities as well as the corresponding adapter method. Provider-defined capability keys may be added. Mail Core ignores unknown keys and treats absent known keys as unsupported; consumers preserve or ignore keys they do not understand.
+
+Built-in Provider config interfaces (`GmailMailProviderConfig`, `MicrosoftMailProviderConfig`, and `ImapSmtpMailProviderConfig`) are exported for applications that need to type their configuration. They are not extension points for changing built-in adapters.
+
+### Domain types
+
+The Server entry exports API-safe account, identity, folder, label, message, attachment, template, signature, operation, synchronization and submission records, plus their request/result types. `MailAccountView` excludes credential references; `MailProviderAccount` is a separate server-only adapter input and carries an opaque vault reference, not a credential. Persistence-only models are not exposed. `MailPublicError` omits provider-internal messages. `MailOperationContext` carries the acting `actorId` and request `AbortSignal` into service calls.
+
+`MAIL_PROVIDER_CAPABILITIES` lists Mail's recognized capability keys, while `MAIL_PROVIDER_ERROR_CATEGORIES` lists its recognized Provider error categories. These runtime constants describe current built-in behavior; consumers should still tolerate unknown capability and error values from later releases.
+
+`MailService` exposes these operation groups:
+
+- Provider discovery and account authorization, connection, listing, update and removal.
+- Personal and managed account, folder, message, attachment and operation-log reads; management actions.
+- Identity, signature, label and template CRUD.
+- Personal message/conversation reads, deferred-content retry, message state updates, label changes, moves and deletion.
+- Single and bulk sending, draft save/conflict resolution, and outbound attachment upload/read.
+- Sync run and submission history, pagination, retry and cancellation, plus unread counts.
+
+Output status, folder-type and Provider error category/reason types have `Known...` aliases for currently recognized values and open `Mail...` types for values added by a later compatible release. Inputs that trigger a specific operation remain constrained to the values Mail currently accepts.
+
+## Client entry
+
+### Composition and data access
+
+- The default export registers the Mail Client plugin.
+- `MailWorkspacePage` and `MailWorkspacePageProps` provide the full workspace. `templateVariables` supplies an allowlisted record context for saved template placeholders; it does not associate messages with application records.
+- `MailClient` and `mailClientToken` expose the typed client data layer. Resolve the app-owned instance with `useMailClient()` in React or `app.services.resolve(mailClientToken)` elsewhere; do not construct a separate `MailClient` for normal UI integration.
+- `mailErrorMessage(cause, fallback)` returns the text to show for a failed call: the server's `localizedMessage`, or `fallback`. Code that must react to a specific failure branches on `ApiClientError.reason` from `@nocobase/app-client` instead.
+- `renderMailTemplate()`, `plainTextToMailHtml()`, and `htmlToPlainText()` are supported template/body helpers. `MailTemplateVariables` and `RenderedMailTemplate` describe their data.
+- `MAIL_PLUGIN_NS`, `MAIL_REALTIME_TOPIC`, and `MailRealtimeEvent` expose the translation namespace and invalidation event contract.
+- `MAIL_VIRTUAL_FOLDER_IDS` provides stable query identifiers for built-in cross-account folders. `MAIL_LABEL_COLORS` and `DEFAULT_MAIL_LABEL_COLOR` provide the supported user-label palette and default.
+
+### `MailClient` method groups
+
+- **Providers and accounts:** `listProviders`, `listAccounts`, `startAuthorization`, `connectAccount`, `updateAccount`, `removeAccount`, `getUnreadCount`.
+- **Managed accounts:** `listManagedAccounts`, `listManagementAccounts`, `listManagedFolders`, `listManagedSyncRunsPage`, `listManagedSubmissionsPage`.
+- **Identities and signatures:** `listIdentities`, `updateIdentity`, `listSignatures`, `saveSignature`, `deleteSignature`.
+- **Folders, labels and templates:** `listFolders`, `listLabels`, `createLabel`, `updateLabel`, `deleteLabel`, `listTemplates`, `saveTemplate`, `deleteTemplate`.
+- **Mailbox reads and message actions:** `listMessages`, `listManagedMessages`, `manageMessages`, `listConversationMessages`, `getMessage`, `getManagedMessage`, `retryMessageContent`, `updateMessage`, `updateMessageLabels`, `moveMessage`, `deleteMessage`.
+- **Attachments:** `uploadAttachment`, `downloadAttachment`, `downloadManagedAttachment`.
+- **Compose and drafts:** `sendMessage`, `sendBulk`, `saveDraft`, `resolveDraftConflict`.
+- **Synchronization:** `startSync`, `getSyncRun`, `listSyncRunsPage`, `retrySyncRun`, `cancelSyncRun`.
+- **Delivery history:** `listSubmissionsPage`, `retrySubmission`, `cancelSubmission`.
+
+The TypeScript signatures are the request/result source of truth. For direct HTTP clients, see [HTTP API](http-api.md).
+
+## Reusable components
+
+All components below are exported from `@nocobase/app-plugin-mail/client/components`. Components that call `useMailClient()` require the Mail Client plugin to be registered in the host application.
+
+| Component                           | Exported props and related types                                                                                                                                                                            |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MailAccountCard`                   | `MailAccountCardProps`                                                                                                                                                                                      |
+| `MailAccountConnector`              | `MailAccountConnectorProps`, `MailAccountConnectorLabels`, `MailAccountCredentials`                                                                                                                         |
+| `MailConversationView`              | `MailConversationViewProps`, `MailConversationViewLabels`                                                                                                                                                   |
+| `MailMessageList`                   | `MailMessageListProps`, `MailMessageListLabels`                                                                                                                                                             |
+| `MailProviderCard`                  | `MailProviderCardProps`                                                                                                                                                                                     |
+| `MailRichTextEditor`                | `MailRichTextEditorProps`, `MailRichTextValue`, `MailRichTextEditorLabels`, `MailRichTextEditorInsertOption`, `MailRichTextEditorInsertMenu`, `MailRichTextEditorInsertActions`                             |
+| `MailNavigationIcon`                | No props; displays the user's unread count using the host app services.                                                                                                                                     |
+| `MailLabelManager`                  | No props; reads and edits the current user's labels.                                                                                                                                                        |
+| `MailLabelTag`, `MailLabelColorDot` | `MailLabelTagProps`, `MailLabelColorDotProps`                                                                                                                                                               |
+| `MailSignatureManager`              | `MailSignatureManagerProps`                                                                                                                                                                                 |
+| `MailStatusBadge`                   | `MailStatusBadgeProps`, `MailStatusTone`                                                                                                                                                                    |
+| `MailSyncPolicyFields`              | `MailSyncPolicyFieldsProps`, `MailSyncPolicyValue`                                                                                                                                                          |
+| `MailTemplateManager`               | No props; reads and edits the current user's templates.                                                                                                                                                     |
+| `MailboxSidebar`                    | `MailboxSidebarProps`, `MailboxSidebarLabels`, `MailboxFolderGroup`, `MailboxSmartView`                                                                                                                     |
+| `MailComposer`                      | `MailComposerComponentProps` and shared `MailComposerProps`, `MailComposerRequest`, `MailComposerState`, `MailComposerCompletionResult`, `MailForwardQuote`, `MailTemplateVariables`, `EMPTY_MAIL_COMPOSER` |
+| `MailWorkspaceComposer`             | `MailWorkspaceComposerProps` and the shared composer contracts above.                                                                                                                                       |
+
+`MailComposer` renders one supplied account/request. `MailWorkspaceComposer` also manages account and sender identity selection across eligible accounts. Completion results are open strings; callers should handle known results and provide a fallback for future outcomes.
+
+## HTTP and realtime
+
+The authenticated `/api/mail` routes, payloads, paging, permission resources, error reasons, OAuth callback and Provider webhook are documented in [HTTP API](http-api.md). Prefer `MailClient` for application code. The `mail:messages` realtime event is a user-scoped invalidation signal with no message body; refresh affected Mail data after receiving it or reconnecting.
+
+## Evolution rules
+
+Within a major version, keep existing names, required props and request fields, response meaning, permission checks and event semantics stable. Add fields as optional, add optional component props and Provider methods, preserve unknown capability/status/error/event values, and give consumers safe fallbacks. Reserve removal, required-field additions and semantic changes for a major version with a migration note. Do not make application code depend on implementation paths outside the package export map.

package/skills/nocobase-app-plugin-mail/references/sending-and-drafts.md

@@ -0,0 +1,53 @@
+# Sending and drafts
+
+## Submit through Mail
+
+Resolve `MailService` with `mailServiceToken`, or use the authenticated `POST /api/mail/messages/send` API. Inspect the installed request type and derive the actor from the server session; a browser-supplied owner ID is not authorization. Mail enforces account ownership and rejects inactive accounts.
+
+Supply a stable `idempotencyKey` for one logical send and retain it across transport retries. A key reused with different content is rejected. After a lost response, query submission history or repeat the same logical request with the same key; generating a new key can duplicate mail. Mail owns persisted submissions and outbox/background job delivery, so application code should not add a second provider submission path.
+
+Submission history is available through `MailService.listSubmissions()`, `GET /api/mail/submissions`, and `/dev/mail/logs/send`. A failed request answers the standard error body `{ error: { code, status, reason, domain: 'mail', message, localizedMessage } }`; branch on `reason` (for example `MAIL_IDEMPOTENCY_CONFLICT` or `MAIL_ACCOUNT_INACTIVE`), never on `message`, and show `localizedMessage` when present. A submission's own delivery error is a public Provider error with `code`, `category` and `retryable`. Public views omit internal provider errors, request fingerprints and leases.
+
+## Delivery outcomes and retries
+
+| Status       | Meaning and handling                                                                        |
+| ------------ | ------------------------------------------------------------------------------------------- |
+| `pending`    | Waiting, possibly for scheduled time; cancellable before a worker claims it                 |
+| `submitting` | Submission in progress; observe its result                                                  |
+| `accepted`   | Provider accepted the request; not proof of recipient delivery or reading                   |
+| `failed`     | Inspect the error and retry eligibility; supported retries reuse the stored snapshot        |
+| `unknown`    | Provider may have accepted it; confirm provider-side outcome before deciding further action |
+
+Use `POST /api/mail/submissions/:submissionId/retry` or `/cancel` for eligible persisted submissions. Accepted and unknown submissions cannot be retried or cancelled through these actions. Older records whose snapshots were cleared cannot recover recipient details or be retried. Do not implement retry as “send a new message” for every terminal status.
+
+SMTP can accept some recipients and reject others. The submission remains `accepted` with `SMTP_RECIPIENTS_REJECTED`, accepted/rejected recipient lists and `retryable: false`. Present the partial outcome; only rejected recipients belong in a new send. Avoid resending to everyone based on the presence of an error field.
+
+## Drafts, attachments and composition
+
+Local drafts support every sending provider. Autosave writes locally after two seconds of inactivity (maximum ten seconds during continuous input), never disables editing or sending, and reports failure only in the autosave indicator. Imported provider drafts are localized before editing; no remote mirroring or conflict prompt is used. Close flushes changes in the background. Preserve stable draft keys, revisions and closed-draft records so late saves cannot recreate a consumed draft.
+
+Retain the attachment IDs returned when uploading or reopening a draft. Local upload identities differ from provider attachment IDs; Mail keeps uploads alive while referenced by a live draft or outgoing submission snapshot. Reopened or rescheduled drafts must use the retained file content, including after page reload. Do not reconstruct attachment references from display names or remove a shared upload when another draft still owns it.
+
+Keep sender-account selection, signatures, templates, scheduled time and attachments consistent with the selected account. Templates resolve variables when applied and preserve unknown placeholders. Forwarded source HTML and the sender's new comment are separate content; preserve that split across editing, autosave and recovery.
+
+Sending clears the composer and browser draft recovery for every result, including failure, unknown delivery and partial acceptance. Validation errors before handoff preserve editing. Transport uncertainty keeps the original request in browser outgoing records; resume it with the same idempotency key instead of creating another draft or submission.
+
+## Scheduled and separate sending
+
+Scheduled sends persist their message snapshot and run through Mail's outbox and the application jobs service. Browser timers are insufficient. The account and provider must still be available when the worker executes.
+
+Ordinary scheduled messages remain in Drafts with `scheduledSend` metadata. Use the submission cancellation action before editing, deleting or sending the draft again; wait for cancellation success before opening the composer. Cancellation restores the same draft and retains recipients, content and attachments. Pending schedules are cancellable before sending starts. Accepted, failed and unknown delivery all remove the draft; outgoing snapshots remain available for inspection and eligible retries. The upgrade migration restores draft associations for existing ordinary schedules. Separate sending continues to use batch history.
+
+`POST /api/mail/messages/sendBulk` creates separate per-recipient submissions. The shared development composer at `/dev/mail/send` offers both ordinary sending and Send separately. Separate sending deduplicates at most 100 recipients and requires empty Cc/Bcc; each child owns its content and attachment references; the source draft is removed once every child request is persisted.
+
+Display grouped history using `GET /api/mail/submissions?bulkOnly=true&groupByBatch=true`. Pages (`page`, `pageSize`) and `meta.total` count complete batches. Expand the parent for recipient details; parent actions apply only to eligible children in that batch. Refresh pending results and retry only failed eligible children, preserving accepted and unknown outcomes.
+
+## Sent-folder refresh
+
+Accepted submissions schedule mailbox refreshes immediately and after 5 and 30 seconds, allowing delayed provider visibility. A request during active sync schedules a follow-up. Synced messages, keyed by account and provider message ID, populate the sent folder; application code should not manufacture a second sent-message record.
+
+A refresh error does not mean delivery failed and must never resend an accepted submission. For IMAP/SMTP, sent copies depend on `sentCopyMode`; read [sent-copy configuration](configuration-and-accounts.md#imapsmtp-boundaries-and-sent-copies). `IMAP_SENT_COPY_FAILED` retains accepted delivery and calls for archive diagnosis, not another send.
+
+## Verify this path
+
+Use provider mocks or an authorized test mailbox to verify stable-key retries produce one provider submission, a key with changed content is rejected, and a lost response does not generate a new send. For the changed behavior, cover unknown results, partial SMTP acceptance, accepted delivery with failed sent-copy saving, restored draft attachments, job-backed scheduling, or batch retry eligibility as applicable. Distinguish provider acceptance from actual recipient receipt in the reported results.

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

@@ -0,0 +1,57 @@
+# Synchronization and diagnostics
+
+## Start and observe synchronization
+
+Use `MailService.startSync()` or `POST /api/mail/accounts/:accountId/sync`. The workspace's all-mailbox action targets active accounts supporting incremental synchronization; selecting an account narrows the scope. Observe history through `GET /api/mail/syncRuns` (paged by `page` and `pageSize`), a run through `GET /api/mail/syncRuns/{syncRunId}`, or `/dev/mail/logs/sync`.
+
+Automatic synchronization is configured globally through `mail.automaticSyncIntervalMs` or `MAIL_AUTOMATIC_SYNC_INTERVAL_MS`. It defaults to `300000` milliseconds, minimum `60000`, and applies to both existing and new accounts. The runtime checks due accounts every minute. Account forms and account-update APIs do not set independent automatic intervals.
+
+`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.
+
+## 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.
+
+Google recommends keeping Gmail batches at or below 50 calls; Mail uses 10 to bound response size. A batch-level transport failure retries the page; an individual embedded error is preserved and surfaced. Quota pacing uses the per-user and per-project limits configured for the Gmail provider with 20% headroom. The defaults are 6,000 units/user/minute and 1,200,000 units/project/minute. Since pacing state is process-local, split those quota values among app processes sharing the same project or centralize sync work on one process.
+
+HTTP 403 is not automatically a quota failure. `rateLimitExceeded` and `userRateLimitExceeded` (and HTTP 429) are retryable; authorization/permission 403 responses are not. Retryable sync errors honor `Retry-After` and use truncated exponential backoff with random jitter, capped at 64 seconds. After 12 consecutive scheduled retries, the run is marked failed for an operator to inspect and retry. A local quota override cannot change the quota granted by Google.
+
+Official references: [Gmail API quotas and retry guidance](https://developers.google.com/workspace/gmail/api/reference/quota?hl=zh-cn) and [HTTP batch behavior and limits](https://developers.google.com/workspace/gmail/api/guides/batch?hl=zh-cn). [verified: 2026-09-26]
+
+## Recovery and correctness
+
+Mail captures a provider baseline before scanning history, then alternates history and incremental pages with separate persisted cursors. It serializes account writes and commits messages, checkpoints and the next outbox task together. The outbox relay submits background jobs; each job advances a bounded step. Application code should not enqueue independent sync jobs or write checkpoints directly.
+
+Startup and periodic maintenance recover expired workers and published job deliveries without progress. Recovery uses task revisions and leases so old workers cannot advance newer state. Pending delayed retries retain their schedule. An idle-looking run is not evidence that a replacement run should be created; inspect its public progress and the jobs backend first.
+
+A provider cursor error starts a fresh scan of the configured history range with a new baseline. Never set a failed cursor to “current” and report completion without scanning, because that loses unseen changes. Existing messages and local metadata remain available; history must not overwrite newer synchronized state or resurrect a message deleted during the scan. A rescan does not reconcile deletions that have already disappeared from provider history.
+
+The owner can cancel an active run through `POST /api/mail/syncRuns/{syncRunId}/cancel` and retry a failed or cancelled run through `POST /api/mail/syncRuns/{syncRunId}/retry`. Keep retry and cancellation behind the service/API transitions rather than editing run status.
+
+## Incomplete content
+
+Keep visible records with `contentStatus: deferred` or `failed`. IMAP bounds encoded body input and retained decoded text to 2 MiB each per message during background synchronization (16 MiB for manual retries using bounded chunk requests), while retaining envelope and attachment metadata for deferred content. Attachments stream separately on demand; large attachments alone do not defer a small body. Parsing failures retain a durable message identity rather than blocking the whole mailbox.
+
+The owner can load or retry content through the message detail action or `POST /api/mail/accounts/:accountId/messages/:messageId/retryContent`. This fetch is independent of the background size limit and can use memory proportional to the full message. Preserve current read/starred state, labels, notes and follow-up markers during a content retry.
+
+Logs expose `recovering` and `historyComplete` to distinguish recovery from unfinished history import. A sync run can finish as `partial` when content remains unresolved. Its `pendingMessages` count describes the completion snapshot; loading content later does not rewrite historical log totals. Later synchronization refreshes those counts. Distinguish this from a `failed` batch caused by a network or authentication error.
+
+## Diagnostic order
+
+| Symptom                      | Check and response                                                                                                                                    |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Mail capability absent       | Client/Server registration, migrations and enabled provider configuration; inspectors cover composition only                                          |
+| Account cannot send or sync  | Account status, provider availability and ownership; `reauthorizationRequired` requires reconnecting                                                  |
+| Task remains pending         | Application jobs service, Mail runtime, migration state and server logs; page refresh cannot execute queued work                                      |
+| Progress stops after restart | Lease/delivery recovery and pending retry schedule, using the same application database                                                               |
+| History appears incomplete   | Configured start date, ongoing history progress and incomplete-content records; do not introduce a total import cap                                   |
+| Gmail returns quota 403      | Check `rateLimitExceeded`/`userRateLimitExceeded`, real project quotas, batch subrequest count, and whether all app processes share one pacing budget |
+| Cursor fails repeatedly      | Provider authorization and cursor recovery; preserve the date-scoped rescan instead of skipping to now                                                |
+| IMAP external state differs  | New-UID sync does not fully reconcile external flags, deletions or moves                                                                              |
+| Sent mail missing            | Provider visibility and sent-copy mode; delivery outcome is authoritative for whether to resend                                                       |
+
+Personal diagnostics require workspace permission and ownership. Cross-user operation history is available under admin permission as two paged lists, `GET /api/mail/settings/syncRuns` and `GET /api/mail/settings/submissions` (`page`, `pageSize` up to 100, `meta.total`); `GET /api/mail/settings/accounts` lists the accounts with API-safe metadata. It has no built-in settings page. Keep credential references, cursors, leases and internal provider errors out of application diagnostics.
+
+## Verify this path
+
+For synchronization integration, verify multiple history pages and a message arriving during history import, not merely one successful list request. For recovery changes, verify restart with retained progress, rejection of stale worker writes and invalid-cursor rescan without skipped changes. For incomplete-content UI, verify continued visibility, independent retry and metadata preservation. Confirm local NocoBase labels/notes survive resync. Run only the scenarios relevant to the requested change; provider and job executor mocks do not prove a deployment's live connectivity.