qubrics-token-efficient-usage · v1.0 · 2026-11-10 · sha256 763618dc196f35e5

qubrics-token-efficient-usage v1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/763618dc196f35e5.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_njzngrktkc7fpbnj/763618dc196f35e58fa1deb165703f3e77cd47eeaf73ea5d036f1e6ff371472f.json

Then /plugin install qubrics-token-efficient-usage@markdownregistry-njzngrktkc7fpbnj in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: qubrics-token-efficient-usage
description: "Use when the question is about *how to call* Qubrics cheaply, not what to send: choosing batch vs. looped sends, mailbox search/count/batch-read vs. full fetches, sync deltas, cursor pagination, ETags/conditional requests, idempotency keys, or picking between MCP, the qubrics CLI, an SDK, or direct HTTP. Trigger for reducing token/round-trip/API-call cost, avoiding broad mailbox or log fetches, or optimising a polling/sync loop.\n\nThis is a routing/cost-decision skill, never a content-authoring one. If the request asks to write, draft, compose, or format the actual JSON body, subject, text, or attachment bytes of an email — even a single email, even one with an attachment, even inside a larger batch — do NOT use this skill; route that to qubrics-send-email or qubrics-attachments instead. Ask yourself: is the user asking \"what's the cheapest way to call Qubrics,\" or \"what should this email/attachment contain\"? Only the former belongs here."
license: Apache-2.0
metadata:
  author: qubrics
  version: "1.0"
---

# Qubrics token-efficient usage

Use this skill to choose the lowest-cost Qubrics route that still answers the task correctly.

## Boundaries

Before any CLI or SDK connection check or task command, start an isolated child process with inherited `QUBRICS_API_KEY`, `SENDMUX_API_KEY`, `QUBRICS_ACCESS_TOKEN`, `SENDMUX_ACCESS_TOKEN`, `QUBRICS_PROFILE`, `SENDMUX_PROFILE`, `QUBRICS_BASE_URL` and `SENDMUX_BASE_URL` cleared. Load only the intended credential from the user's secret store; for profile-based calls, leave direct credentials unset and select the intended `--profile`. Use the authorised endpoint before transmitting credentials and keep credentials out of arguments and output. Apply this precondition when reusing a durable profile too.

For the documented keyless self-registration flow, complete registration first, then verify the newly saved profile before content reads, sending or other task work. For existing credentials or profiles, verify the returned connection identity and any authorised mailbox selection against the intended account and credential before task work. A permission grant alone does not establish the intended identity. If identity differs or cannot be verified, stop and resolve it with the user rather than reading or mutating another account.

- Do not ask the user to paste an API key.
- For API-key authentication, use `smx_mbx_*` keys for normal Mailbox calls.
- For a self-registered agent, reuse one durable CLI profile. Mailbox reads become available after provisioning, before owner approval; Sending stays blocked until owner approval.
- For API-key authentication, use `smx_root_*` for Management calls.
- Do not default to MCP for every task. MCP is best when the required tool is curated; CLI and SDK cover broader surfaces.
- Keep real attachment bytes outside model context and route their mechanics to `qubrics-attachments`; use the attachment route reference below.
- Do not read full mailbox bodies, every message, or every log row unless the user asks for full content and narrower calls cannot answer.

Choose the authentication connection, then its already-approved product surface. For an existing OAuth profile, use the already-known approved surface from its granted permissions or setup context. If that surface is unknown, show the surface-specific alternatives below and ask which one the profile grants; there is no universal Mailbox default.

| Authentication connection | Validate with | Ownership boundary |
| --- | --- | --- |
| Existing CLI or REST OAuth profile | The selected CLI operation: `mailbox:get-connection`, `management:get-connection`, or `sending:get-connection` | Explain that the check stays within the profile's approved surface, scopes, and mailboxes. `qubrics-cli` owns login and refresh. |
| SDK application credentials | The selected SDK operation: `mailboxGetConnection`, `managementGetConnection`, or `sendingGetConnection` | The application supplies SDK credentials; this is not a CLI profile check. |
| Already-connected MCP session | The selected MCP operation: `mailbox_get_connection`, `management_get_connection`, or `sending_get_connection` | This validates only that MCP session. `qubrics-mcp-setup` owns hosted MCP OAuth setup; it is not an alternate view of a REST profile. |

These checks need no mailbox selector and send no email. Public OpenAPI discovery does not validate credentials.

## Surface choice

| Situation                               | Use                                 | Why                                                           |
| --------------------------------------- | ----------------------------------- | ------------------------------------------------------------- |
| Connected agent and curated tool exists | MCP tool                            | Small schema and no SDK boilerplate.                          |
| One-off terminal task                   | `qubrics` CLI with `--json`         | Direct, scriptable, exposes the full generated operation set. |
| Application code or repeated workflow   | SDK for the project already in use  | Reuses client setup, pagination, headers, and retry helpers.  |
| MCP lacks the needed operation          | CLI for terminal work, SDK for code | Do not invent uncurated MCP tools.                            |
| No package/tooling available            | Direct HTTP                         | Keep request bodies and headers aligned to OpenAPI.           |

Credential ownership follows the surface. For a durable CLI agent profile, the CLI automatically exchanges and caches the one-hour delegated token for `sending:*` commands. SDK callers supply a compatible `apiKey` or `accessToken` (or their own provider callback); SDK helpers do not read or update CLI profile state.

## Cheapest-call map

| Task                            | Cheapest correct default                                                                                                               |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Send one outbound email         | `sending_send_email`, CLI `sending:send`, SDK `sendingSendEmail`; include `Idempotency-Key`.                                           |
| Send multiple outbound emails   | `sending_send_email_batch`, CLI `sending:send:batch`, SDK `sendingSendEmailBatch`; do not loop single sends.                           |
| Send or read attachments        | Use the attachment route reference below.                                                                                              |
| Count matching mailbox messages | `mailbox_count_messages`, CLI `mailbox:count-messages`, SDK `mailboxCountMessages`.                                                    |
| Search mailbox text             | `mailbox_search_message_snippets`, CLI `mailbox:search-message-snippets`, SDK `mailboxSearchMessageSnippets`; then fetch selected IDs. |
| Read several known messages     | `mailbox_batch_get_messages`, CLI `mailbox:batch-get-messages`, SDK `mailboxBatchGetMessages`.                                         |
| Update/delete several messages  | Batch update/delete after explicit confirmation.                                                                                       |
| Resume broad mailbox sync       | `mailbox_get_changes`, CLI `mailbox:get-changes`, SDK `mailboxGetChanges`.                                                             |
| Resume filtered mailbox sync    | CLI/SDK `mailbox:query-message-changes` / `mailboxQueryMessageChanges`; MCP does not curate it yet.                                    |
| Watch live mailbox events       | CLI/SDK `mailbox:stream-events` / `mailboxStreamEvents`; MCP does not curate it yet.                                                   |
| Scan threads                    | List threads, then fetch one thread or its messages.                                                                                   |
| Manage domains/mailboxes/keys   | Management MCP for curated create/list/get/update/suspend/resume/key tools; CLI/SDK for uncovered lifecycle work.                      |
| Manage sending accounts         | CLI/SDK; MCP does not curate provider tools yet.                                                                                       |
| Manage webhooks                 | MCP for list/create/test; CLI/SDK for get/update/delete/rotate/delivery payloads.                                                      |
| Inspect spend, logs, metrics    | Metrics first; use `management:list-email-logs` / `managementListEmailLogs` for filtered summaries, then `management:get-email-log` / `managementGetEmailLog` for one selected row. |

### Attachment route reference

`qubrics-attachments` owns the detailed upload/download procedures and current direct-upload limits.

When comparing local-file routes, state how bytes move and which size authority applies for each alternative below, then recommend the one matching the user's environment:

1. **Terminal:** recommend CLI `--attach` for a one-off task. It uploads directly outside model context; server-enforced direct-upload limits apply. There is no presign-limit response.
2. **Application code:** name `sendEmailWithFiles` or `uploadAttachmentFromFile` from `@qubrics/sending/node`, or `uploadMailboxAttachmentFromFile` from `@qubrics/mailbox/node`. These helpers upload directly outside model context; server-enforced direct-upload limits apply, with no presign-limit response.
3. **Connected MCP:** name `sending_create_attachment_upload` for Sending, or `mailbox_upload_attachment` with `presign_upload_url=true` for Mailbox. Both use presigned external transfer outside model context. For Sending, obey the upload intent's returned `max_size_bytes`; Mailbox accepts requested `size_bytes` up to 7,500,000.

For tiny agent-authored content, MCP inline `content_base64` is available only after measuring the decoded content at no more than 32,768 bytes; a filename or file type cannot establish eligibility.

For presigned Sending uploads, the intent returns a temporary `upload_id`; take the final `attachment_id` from the successful external `PUT` response. A successful external Mailbox upload returns the `blob_id` for Mailbox sends. Never use MCP `file_path` or real-file inline base64.

For an agent with no key, avoid manual protocol calls and token copying:

```bash
qubrics agent:register my-agent --default --json
qubrics mailbox:me:get --profile my-agent --json
qubrics agent:invite-owner owner@example.com --profile my-agent --json
```

Register once, then reuse the durable profile across processes. For this self-registered agent, sending has two owner gates: the owner accepts the invitation, then explicitly approves sending. Once both are complete, use the same profile with `sending:*`; the CLI handles the one-hour delegated token exchange and cache.

Explain the storage boundary alongside this setup: the inbox is capped at 500 MiB before approval. Owner-approved sending raises it to at least 5 GiB first. Revoking sending does not itself change the current inbox storage allocation.

## Read less

For mailbox questions, reduce the result set before reading content:

1. Count when the user asks "how many" or when the query may be broad.
2. Search snippets with a small `limit` when the user needs examples; choose from the returned `message_id`, `subject`, and `preview` fields.
3. Batch-get only selected message IDs.
4. Request clean body/content only when message text affects the answer.

CLI:

```bash
qubrics mailbox:count-messages \
  --query q=invoice \
  --query is_unread=true \
  --json

qubrics mailbox:search-message-snippets \
  --query q=invoice \
  --query is_unread=true \
  --query limit=10 \
  --json

qubrics mailbox:batch-get-messages \
  --body '{
    "ids": ["eml_abc", "eml_def"],
    "body_mode": "clean_json",
    "max_body_chars": 4000,
    "strip_quotes": true,
    "strip_signature": true,
    "include_attachments": "metadata"
  }' \
  --json
```

## Write fewer requests

Batch when there is more than one target.

For API-key or delegated-token authentication, name the Sending authority alongside the recommended call: a send-capable `smx_mbx_*` key or owner-approved Sending-resource `smx_agent_*` token. This applies to both single and batch sends.

```bash
qubrics sending:send:batch \
  --idempotency-key "$IDEMPOTENCY_KEY" \
  --body-file ./messages.json \
  --json

qubrics mailbox:batch-update-messages \
  --body '{
    "ids": ["eml_abc", "eml_def"],
    "seen": true,
    "if_in_state": "state_from_prior_read"
  }' \
  --json
```

For batch sends, inspect every per-message result before reporting success. Batch can contain mixed outcomes.

## Sync by delta

Use sync endpoints instead of re-listing stable data.

Choose the sync route that matches the requested view: broad mailbox state uses `mailbox:get-changes` / `mailboxGetChanges`; a filtered message view uses `mailbox:query-message-changes` / `mailboxQueryMessageChanges`.

Broad mailbox sync:

```bash
qubrics mailbox:get-changes \
  --query types=messages,folders,threads \
  --query messages_since_state="$MESSAGES_STATE" \
  --query folders_since_state="$FOLDERS_STATE" \
  --query threads_since_state="$THREADS_STATE" \
  --query limit=100 \
  --json
```

This multi-resource sync requires `types=messages,folders,threads`; omitting `types` deliberately selects the legacy message-only response. Before the next call, persist each returned resource's `new_state` and `has_more`. Map `data.types.messages.new_state`, `data.types.folders.new_state`, and `data.types.threads.new_state` to the matching `*_since_state` input. Continue each resource whose saved `has_more` is true independently with its saved state; a narrower response updates only the resource it requested.

For a message-only continuation, use the selected resource's fields exactly:

```bash
qubrics mailbox:get-changes \
  --query types=messages \
  --query messages_since_state="$NEXT_MESSAGES_STATE" \
  --query limit=100 \
  --json
```

After every response, replace the current response, set `NEXT_MESSAGES_STATE` from its `data.types.messages.new_state`, and repeat only while that same latest response's `data.types.messages.has_more` is true.

Filtered message sync:

```bash
qubrics mailbox:query-message-changes \
  --query since_query_state="$QUERY_STATE" \
  --query q=invoice \
  --query is_unread=true \
  --query limit=100 \
  --json
```

After every response, set `QUERY_STATE` from its `data.new_query_state`, and continue with the same filters only while that same latest response's `data.has_more` is true and the next page is needed.

A polling-loop answer must distinguish sync continuation from cursor-paginated list calls. For the latter, preserve the same filters and a small bounded limit, count matches cumulatively across pages, stop immediately when the local threshold is reached even mid-page, and follow the returned `pagination.next_cursor` only while another list page is needed. At the start of every polling tick, call each enabled sync route once with its saved state and perform each enabled conditional-log read once, even when the prior sync response had `has_more=false`; within that tick, add one call for every requested continuation page.

Use the public delivery-log seams exactly:

- For filtered summary pages, use CLI `management:list-email-logs` or SDK `managementListEmailLogs`. Preserve only supported filters (`status`, `from_date`, `to_date`, `provider_id`, `search`), and map the returned `pagination.next_cursor` to the next `cursor` input.
- For repeated reads of one known log, CLI `management:get-email-log --if-none-match "$ETAG"` can send an ETag supplied from elsewhere, but CLI output is the API JSON body—not an HTTP status/header envelope. It cannot acquire or refresh the ETag or branch on `304`.
- For the first metadata-bearing read and every later `304`-aware read, use the supported SDK packages directly; `priorEtag` is absent on the first call:

```ts
import { responseEtag } from "@qubrics/core";
import { createManagementClient, managementGetEmailLog } from "@qubrics/management";

const client = createManagementClient({ apiKey: process.env.QUBRICS_API_KEY! });

const result = await managementGetEmailLog({
  client,
  path: { public_id: logId },
  headers: priorEtag ? { "If-None-Match": priorEtag } : {},
  throwOnError: false,
});

if (result.response?.status === 304) {
  // Unchanged representation; there is no response body.
} else if (result.error) {
  // Handle the unsuccessful response.
} else {
  const log = result.data?.data;
  const nextEtag = responseEtag(result.response);
}
```

The terminal delivery statuses are `sent`, `failed`, and `rejected`. A `304` means the representation is unchanged; it does not establish a terminal delivery status.

## Transfer less

- Use small `limit` values on list calls.
- Follow `pagination.next_cursor` only until enough evidence has been gathered.
- Prefer summary or metrics endpoints before log lists.
- Use `If-None-Match` for repeated detail reads that previously returned an `ETag`.
- Use `If-Match` for updates when the prior read returned an `ETag`.
- For inbound attachments, fetch metadata and use the short-lived `download_url`; if it expires, re-fetch metadata instead of building URLs manually.
- For outbound attachments, follow the attachment route reference above.

CLI conditional examples:

```bash
qubrics management:get-email-log \
  --path public_id=dlog_abc \
  --if-none-match "$ETAG" \
  --json

qubrics management:update-mailbox \
  --path public_id=mbx_abc \
  --if-match "$ETAG" \
  --body '{"display_name":"Agent Inbox"}' \
  --json
```

SDK helpers:

```
import {
  conditionalHeaders,
  idempotencyHeaders,
  paginate,
  responseEtag,
} from "@qubrics/core";

const headers = conditionalHeaders({ ifNoneMatch: priorEtag });
const writeHeaders = {
  ...conditionalHeaders({ etag: priorEtag }),
  ...idempotencyHeaders(operationKey),
};
```

## Retry safely

Use `Idempotency-Key` on supported mutations so retrying does not create duplicate work.

Good candidates:

- `sending:send` and `sending:send:batch`.
- `mailbox:send-message`.
- Management creates, mailbox key creation, suspend/resume, provider mutations, webhook create/rotate/test.

When retrying application code, prefer SDK retry helpers only for safe reads or idempotent writes. Non-idempotent writes should fail rather than risk duplicate side effects.

## Routing

- Setup, key scopes, first call: `qubrics-getting-started`.
- Email send bodies and SMTP-vs-HTTP choice: `qubrics-send-email`.
- Attachment upload/download mechanics: `qubrics-attachments`.
- Mailbox read/search/sync/triage/reply details: `qubrics-mailbox-agent`.
- Management domains, mailboxes, webhooks, billing, logs: `qubrics-management`.
- CLI syntax and profiles: `qubrics-cli`.
- MCP installation and client config: `qubrics-mcp-setup`.