v1.0 to v1.0

+ description: "Operate inside an already-existing Sendmux mailbox on behalf of an AI agent: read, search, count, sync, triage, file, delete, thread, or reply to messages using an API key, scoped agent token, or authorised OAuth profile. Trigger when the user wants an agent to inspect an inbox, find or mark messages, resume a prior sync state, or send a reply from that mailbox's identity. Do NOT use this for creating, provisioning, or administering mailboxes, domains, or API keys themselves — that setup and admin work belongs to sendmux-management, not this skill."

+ - When explaining a self-registered agent's storage lifecycle, include every field in the lifecycle table below. Registration does not itself grant sending; route owner-approved agent sends to `sendmux-send-email` and the Sending API.

+ - If a credential grants more than one mailbox, include `mailbox_id`; otherwise omit it. CLI and REST keep `mailbox_id` in the query even when the operation also has a JSON body, and CLI spells that `--query mailbox_id=<id>`. MCP uses the tool's declared top-level `mailbox_id` argument.

+ | Self-registered lifecycle field | Required fact |

+ | ------------------------------- | ------------- |

+ | Before owner approval | Inbox storage is capped at 500 MiB. |

+ | First owner-approved sending | Inbox storage rises to at least 5 GiB. |

+ | Sending later revoked | Revocation alone does not change the current storage allocation; durable read and receive continue while the registration remains active. |

+ For an existing OAuth CLI profile, a complete validation and selection answer uses `mailbox:get-connection --profile <profile> --json` before accessing messages, with no mailbox selector, and states that login or refresh help routes to `sendmux-cli`. For multiple authorised mailboxes, the response lists `data.mailboxes[].id`; choose one returned `id` and supply it as `mailbox_id` on later mailbox operations. Hosted MCP uses its own OAuth resource.

+

+ Use `q` only for full-text search text. Express unread status, sender, and date constraints through the separate `is_unread`, `from`, `after`, and `before` filters; do not encode filter operators inside `q`.

+

+ throwOnError: true,

+ const ids = snippets.data.data.snippets.map((item) => item.message_id);

+ if (ids.length > 0) {

+ const messages = await mailboxBatchGetMessages({

+ client,

+ body: {

+ ids,

+ body_mode: "clean_json",

+ max_body_chars: 4000,

+ strip_quotes: true,

+ strip_signature: true,

+ include_attachments: "metadata",

+ },

+ });

+ }

+ Use only the returned identity or an identity the user supplied and verified; never invent an owner name or email address.

+

+ For a local file through connected MCP:

+ 1. State the ownership handoff first: keep the reply and later send in `sendmux-mailbox-agent`, and route local byte handling to `sendmux-attachments`.

+ 2. Read the actual numeric file size; do not infer it from the filename.

+ 3. Choose the path from that numeric measurement:

+ - No numeric size supplied or measured: eligibility is unknown; measure before choosing an upload path.

+ - 1 through 7,500,000 bytes: call `mailbox_upload_attachment` with `presign_upload_url: true`, `filename`, `content_type`, and the exact `size_bytes`.

+ - Above 7,500,000 bytes: split the file or send a link to externally hosted content.

+ 4. Treat the returned `upload_url`, `method`, and `headers` as short-lived capabilities. Transfer the bytes outside model context using the exact returned method and headers. Keep that metadata in memory or an ephemeral stdin/file-descriptor channel: do not put it in literal process arguments or retained output, and do not add a Sendmux bearer to the upload request.

+ 5. A successful external upload returns the `blob_id`. Put that `blob_id` in the later `mailbox_send_message` attachment; do not substitute a Sending `attachment_id`.

+ Do not give MCP a local `file_path`, infer shared filesystem access, or inline a real PDF as base64. CLI `sendmux mailbox:send-message --attach ./report.pdf` and the Node or Python SDK file helpers remain the local-file alternatives.

+ The draft may be prepared before approval. Call `mailbox_send_message` only after the user approves the exact recipient, subject, body, and attachment, and use an `Idempotency-Key` for the retryable send.

+ Store the returned `new_query_state` and pass it as `since_query_state` on the next filtered sync. Follow `has_more` with the same filters when more changes remain. Broad `mailbox:get-changes` returns a separate resource `new_state`; never use that as a filtered-query token.

+ - When filtered query sync rejects an unusable `since_query_state` after the other parameters are validated, start a fresh baseline by repeating `mailbox:query-message-changes` with the same filters and without `since_query_state`; do not substitute the resource state from `mailbox:get-changes`. The fresh baseline does not recover missed deltas, so reconcile the current filtered messages first when continuity matters, then save its new query state. Other `400 invalid_parameter` responses require correcting the named filter, sort, thread, or limit parameter.

+ - Mutation or resource-state `409 conflict`: re-read the current resource state before retrying; an idempotency conflict requires reconciling the existing request rather than forcing it.