feat(core): support REST API v3 mail/mailbox methods — v3 whitelist + list wiring, integration tests, and new-method monitoring

[IgorShevchik]

🚧 Release blocker for the next release (v1.2.0 — see #121).

Context

Bitrix24 shipped a new family of REST v3 mail.* methods (mailbox, message, recipient):

📚 https://apidocs.bitrix24.com/api-reference/rest-v3/mail/mailbox/index.html

The SDK does not surface any of them yet. The v3 method whitelist in
packages/jssdk/src/core/version-manager.ts:21-44
(#supportMethods) currently only contains /batch, /scopes, /rest.scope.list, the /documentation
endpoints, /main.eventlog.* and /tasks.task.*. Because routing is gated by this list
(isSupport() → #v3Support()), calling a mail.* method through b24.actions.v3.*.make() today throws
SdkError with code JSSDK_CORE_METHOD_NOT_SUPPORT_IN_API_V3, and automaticallyObtainApiVersion() silently
falls back to v2.

Good news: the list plumbing already exists — b24.actions.v3.callList
(actions/v3/call-list.ts) and b24.actions.v3.fetchList
(actions/v3/fetch-list.ts) implement cursor-based
pagination over { method, idKey, customKeyForResult }. So enabling mail lists is mostly a matter of
whitelisting the methods and confirming the response-grouping key per method.

New v3 mail.* surface to cover

Mailbox

• mail.mailbox.list — list (current user's mailboxes)
• mail.mailbox.get
• mail.mailbox.field.list — list (available mailbox fields)
• mail.mailbox.field.get
• mail.mailbox.senders

Message

• mail.message.list — list (filter by mailbox, date, attachments, …)
• mail.message.get
• mail.message.field.get
• mail.message.thread
• mail.message.forward
• mail.message.movetofolder
• mail.message.createchat
• mail.message.createtask

Recipient

• mail.recipient.listcontacts — list-style (address-book search)

mailservice.* (mailservice.list/get/update/delete/fields) showed up in the search too, but appears to be
the older surface — verify the API version before touching it; this issue targets the rest-v3 mail.*
family only.

Scope / acceptance criteria

1. Core — whitelist + list methods

• Add the v3 mail.* methods to #supportMethods in
  version-manager.ts:21-44 (keep the inline
  // done annotation convention; only mark done once verified against a live portal).
• For each list method (mail.mailbox.list, mail.message.list, mail.mailbox.field.list,
  mail.recipient.listcontacts), confirm the correct idKey and customKeyForResult (the response-grouping
  key) against the live portal / OpenAPI — do not assume items/id. Document the values so callers can
  use actions.v3.callList.make / fetchList.make.
• Verify automaticallyObtainApiVersion() and automaticallyObtainApiVersionForBatch() now resolve these
  methods to ApiVersion.v3, and that mixing mail + non-whitelisted methods in a batch still degrades to v2 as
  expected.
• Add any public mail types/enums and re-export them from
  packages/jssdk/src/index.ts (public contract).

2. Tests

• Add integration coverage under test/integration/ (real portal, no mocks per
  .github/contributing/testing.md): at minimum mail.mailbox.list /
  mail.message.list via actions.v3.callList + fetchList, plus a representative get and a batch path.
• Document the new webhook scope requirement (mail) in AGENTS.md → Webhook scopes, alongside
  the existing crm/tasks/user/im/main note.
• Consider an under-load scenario for mail.message.list paging if message volumes are large.

3. Monitoring of new methods

The v3 whitelist is hand-maintained and silently drifts whenever Bitrix24 ships new v3 methods (this mail family
is exactly that drift). The header comment in version-manager.ts already points at the source of truth
(https://{portal}/rest/api/{user_id}/{webhook}/documentation and the
rest-v3 OpenAPI).

• Add a script (in the style of scripts/docs-*.mjs) that diffs the live v3 OpenAPI/documentation against
  #supportMethods and reports newly-available methods not yet in the whitelist.
• Wire it as a CI guard / scheduled check (cf. chore(docs): auto-generate prerender pages list from filesystem + CI guard #96, docs-lint: detect frontmatter links: pointing at non-existent files in the repo #117) so new v3 methods surface as a flag instead of
  going unnoticed.
• Extend the maintenance playbook (.github/contributing/maintenance.md)
  with a "new v3 methods" triage step.

Out of scope

• Documentation pages under docs/content/docs/ and the skills/ recipes — track separately once the core
  surface lands (skills must be updated in the same PR per AGENTS.md, but full doc pages can follow).
• mailservice.* (pending API-version confirmation).

Related

• v3 whitelist: packages/jssdk/src/core/version-manager.ts:21-44
• list actions: actions/v3/call-list.ts, actions/v3/fetch-list.ts
• v3 routing rules: skills/b24jssdk-rest/SKILL.md
• process: create v1.2.0 milestone and triage open issues against it #121 — v1.2.0 milestone / triage (this is a blocker for it)