sendmux-management · diff
v1.0 to v1.0
33 added, 6 removed. Audit A to A.
---
name: sendmux-management
- description: Manage Sendmux account-level resources with a root API key or authorised OAuth connection. Use for domains, mailbox provisioning, mailbox API keys, sending accounts, webhooks, billing, spend, delivery logs, incoming logs, metrics, and other team administration tasks; route mailbox reading, triage, sync, and replies to sendmux-mailbox-agent.
+ description: "Use this skill for Sendmux account/team administration with a root API key or Management-scoped OAuth connection. This is the go-to skill for domain lifecycle work — create a sending domain, fetch its DNS/zone-file records, verify DNS/MX — even if asked as a single quick step. Also use it for provisioning, suspending, or deleting mailboxes and mailbox API keys; configuring sending accounts/providers; creating, testing, or rotating webhooks; checking billing, spend, or balance; and pulling delivery, incoming, or metrics logs for reporting or admin purposes. This is account/team-level administration, not inbox usage: do not trigger for reading, searching, triaging, syncing, or replying to messages inside a specific mailbox (use sendmux-mailbox-agent), one-off transactional sending (sendmux-send-email), or initial setup/login (sendmux-getting-started)."
license: Apache-2.0
metadata:
author: sendmux
version: "1.0"
---
# Sendmux management
Use this skill for team administration with an `smx_root_` key or a REST OAuth grant with Management access.
## Boundaries
- Do not ask the user to paste an API key or one-time secret.
- Use a root API-key profile or OAuth profile with Management access and the operation's required scopes. OAuth remains limited by the authorising user's current team permissions.
- Agent self-registration does not require Management or a root key. Route a user who only wants an agent inbox to `sendmux-getting-started` and `sendmux agent:register`.
- Do not use management calls to read, triage, sync, or reply from a mailbox; route those tasks to `sendmux-mailbox-agent`.
- Treat create-key and webhook-secret responses as sensitive one-time values. Put them only in the user's chosen secret store or secure output path.
- Confirm destructive operations before deleting domains, mailboxes, mailbox keys, sending accounts, or webhooks.
- Confirm the target resource before suspend, resume, rotate-secret, or test-delivery operations.
## Surface choice
| Task | Preferred surface |
| --- | --- |
| Domains | MCP for list/create/get/zone-file/verify; CLI or SDK for update/delete/filter rules. |
| Mailboxes | MCP for list/create/get/update/suspend/resume/key create/key delete; CLI or SDK for delete and filters. |
| Sending accounts | CLI or SDK. MCP does not curate provider tools yet. |
| Webhooks | MCP for list/create/test; CLI or SDK for get/update/delete/rotate-secret/deliveries/payloads. |
| Billing and spend | MCP `management_get_spend_summary`; CLI or SDK for balance and transactions. |
| Outbound delivery logs and metrics | MCP for list/get logs and metrics; CLI or SDK also work. |
| Incoming logs | CLI or SDK. MCP does not curate incoming-log tools yet. |
For terminal work, use the `sendmux` CLI with `--json`. For application code, use `@sendmux/management` and `createManagementClient`.
- Validate the selected profile with `sendmux management:get-connection --profile work --json` before reading resources. This check requires Management access but no additional read permission. For OAuth login and token lifecycle, use `sendmux-cli`; SDK clients accept `accessToken` instead of `apiKey`, including a provider that resolves the current token before each request.
+ SDK clients accept `accessToken` instead of `apiKey`, including a provider that resolves the current token before each request.
+ ## Check connection and permissions
+
+ Explain the selected connection in this order:
+
+ 1. Validate it with `sendmux management:get-connection --profile work --json`, replacing `work` with the selected profile. This check requires Management access but no additional read permission.
+ 2. Interpret the response using the schema example below. `data.credential.type` identifies `api_key`, `oauth`, or `agent_token`; `data.permissions` contains effective permission names. `data.label` is a server-provided connection display label, not the local CLI profile name. Explain fields without exposing account metadata unnecessarily.
+ 3. Match the requested operation to its advertised scopes and the authorising user's current team permissions. Use the operation-specific mappings in this skill or inspect that operation's `security` entry in the public Management OpenAPI before naming its scope. Scope names cannot be inferred from an operation's name. Login/re-consent chooses requested scopes; automatic token refresh preserves the existing grant rather than choosing extra permissions.
+ 4. Close with the handoffs: OAuth login and token lifecycle → `sendmux-cli`; agent self-registration → `sendmux-getting-started`; mailbox read, search, sync, triage, or replies → `sendmux-mailbox-agent`. Management access does not replace those workflows.
+
+ This synthetic example shows the CLI response shape, not a verified account:
+
+ ```json
+ {
+ "ok": true,
+ "meta": { "request_id": "EXAMPLE_REQUEST_ID" },
+ "data": {
+ "credential": { "id": "EXAMPLE_CREDENTIAL_ID", "name": "Example connection", "type": "oauth" },
+ "label": "Example connection",
+ "team": { "id": "EXAMPLE_TEAM_ID", "name": "Example team" },
+ "mailboxes": [{ "id": "EXAMPLE_MAILBOX_ID", "email": "agent@example.com" }],
+ "permissions": ["domain.read", "billing.read"]
+ }
+ }
+ ```
+
## Efficient defaults
- Use small `limit` values on list endpoints and follow `pagination.next_cursor` only when more rows are needed.
- Use `Idempotency-Key` on create, suspend, resume, rotate-secret, and test mutations that accept it.
- Use `If-None-Match` for repeated detail reads that return `ETag`.
- Use `If-Match` for update or replace operations when the API exposes optimistic concurrency.
- For questions about counts or trends, use summary or metrics endpoints before log lists.
- For one email or webhook delivery, list with filters first, then fetch the selected record.
## Domains
- Use domains for sending setup and hosted mailbox domains.
+ Use domains for sending setup and hosted mailbox domains. The two domain modes are `send_only` for outbound DNS verification and `send_receive` for outbound plus MX verification. Hosted mailboxes require `send_receive`.
MCP tools:
| Action | Tool |
| --- | --- |
| List | `management_list_domains` |
| Create | `management_create_domain` |
| Inspect | `management_get_domain` |
| DNS records | `management_get_domain_zone_file` |
| Verify DNS | `management_verify_domain` |
CLI:
```bash
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:create-domain \
--idempotency-key "$IDEMPOTENCY_KEY" \
--body '{"domain":"example.com","mode":"send_receive"}' \
--json
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:get-domain-zone-file \
--path public_id=mdom_abc \
--json
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:verify-domain \
--path public_id=mdom_abc \
--json
```
SDK:
```ts
import {
createManagementClient,
managementCreateDomain,
managementGetDomainZoneFile,
managementVerifyDomain,
} from "@sendmux/management";
const client = createManagementClient({ apiKey: process.env.SENDMUX_API_KEY! });
await managementCreateDomain({
client,
headers: { "Idempotency-Key": process.env.IDEMPOTENCY_KEY! },
body: { domain: "example.com", mode: "send_receive" },
});
const zone = await managementGetDomainZoneFile({
client,
path: { public_id: "mdom_abc" },
});
await managementVerifyDomain({
client,
path: { public_id: "mdom_abc" },
});
```
Use CLI `management:update-domain` or SDK `managementUpdateDomain` with `If-Match` for mode upgrades. Confirm before delete.
## Mailboxes and keys
- For API-key setup, create mailboxes with a root key and use mailbox keys afterwards for agent mailbox work. A Management OAuth profile can provision with the required scopes; Mailbox runtime needs its own approved access.
+ For API-key setup, create mailboxes with a root key and use mailbox keys afterwards for agent mailbox work. A Management OAuth profile needs `mailbox.admin.create` to create a mailbox, but `mailbox.admin.manage` to create or revoke its mailbox keys. Mailbox runtime needs its own approved access.
- This owner-administered path is separate from self-registration. A self-registering agent uses a durable CLI profile without an existing account or API key; do not create or expose a root key merely to give that agent an inbox.
+ This owner-administered path is separate from self-registration. When explaining self-registration, state that it needs no existing account or API key and saves a durable CLI profile that can read and receive mail without expiry while the registration remains active; full revocation ends that access. Do not create or expose a root key merely to give that agent an inbox.
MCP tools:
| Action | Tool |
| --- | --- |
| List | `management_list_mailboxes` |
| Create | `management_create_mailbox` |
| Inspect | `management_get_mailbox` |
| Update | `management_update_mailbox` |
| Suspend | `management_suspend_mailbox` |
| Resume | `management_resume_mailbox` |
| Create mailbox key | `management_create_mailbox_key` |
| Delete mailbox key | `management_delete_mailbox_key` |
CLI:
```bash
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:create-mailbox \
--idempotency-key "$IDEMPOTENCY_KEY" \
--body '{
"email": "agent@example.com",
"display_name": "Agent Inbox",
"quota_bytes": 1073741824
}' \
--json
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:create-mailbox-key \
--path public_id=mbx_abc \
--idempotency-key "$IDEMPOTENCY_KEY" \
- --body '{"name":"agent-runtime"}' \
+ --body '{"app_name":"agent-runtime"}' \
--json
```
After creating a mailbox key, hand mailbox read/search/reply work to `sendmux-mailbox-agent` with the new `smx_mbx_` key.
Suspend keeps the mailbox and messages but blocks mailbox access. Delete removes the mailbox and revokes associated keys; confirm deletion explicitly.
## Sending accounts
Sending-account management is full CLI/SDK territory until MCP curates provider tools.
CLI commands:
| Action | Command |
| --- | --- |
| List | `sendmux management:providers:list --json` |
| Create | `sendmux management:create-provider --json` |
| Inspect | `sendmux management:get-provider --json` |
| Update | `sendmux management:update-provider --json` |
| Activate | `sendmux management:activate-provider --json` |
| Deactivate | `sendmux management:deactivate-provider --json` |
| Test | `sendmux management:test-provider --json` |
| Limits | `sendmux management:get-provider-limits --json` |
| Stats | `sendmux management:get-provider-stats --json` |
| Usage | `sendmux management:get-provider-usage --json` |
SDK helpers include `managementListProviders`, `managementCreateProvider`, `managementGetProvider`, `managementUpdateProvider`, `managementActivateProvider`, `managementDeactivateProvider`, `managementTestProvider`, `managementGetProviderLimits`, `managementGetProviderStats`, and `managementGetProviderUsage`.
Do not print provider credentials. Put secrets in the user's chosen secret store.
## Webhooks
+
+ OAuth scopes are `webhook.read` for list, inspect, deliveries and payload reads; `webhook.create` for creation; `webhook.update` for updates; `webhook.delete` for deletion; and `webhook.manage` for secret rotation and test delivery.
MCP covers the common create-and-test path:
| Action | Tool |
| --- | --- |
| List | `management_list_webhooks` |
| Create | `management_create_webhook` |
| Test | `management_test_webhook` |
Use CLI or SDK for full lifecycle work:
| Action | CLI command | SDK helper |
| --- | --- | --- |
| Inspect | `management:get-webhook` | `managementGetWebhook` |
| Update | `management:update-webhook` | `managementUpdateWebhook` |
| Delete | `management:delete-webhook` | `managementDeleteWebhook` |
| Rotate secret | `management:rotate-webhook-secret` | `managementRotateWebhookSecret` |
| List deliveries | `management:list-delivery` | `managementListDelivery` |
| Get delivery payload | `management:get-delivery-payload` | `managementGetDeliveryPayload` |
Use `Idempotency-Key` on create, rotate-secret, and test. Store the webhook signing secret at creation or rotation time; it cannot be retrieved later.
## Billing, logs, and metrics
Use read-only summary endpoints before broad log reads.
| Question | Preferred call |
| --- | --- |
| Spend trend | `management_get_spend_summary`, CLI `management:get-spend-summary`, SDK `managementGetSpendSummary`. |
| Current balance | CLI `management:list-balance`, SDK `managementListBalance`. |
| Transaction history | CLI `management:list-transactions`, SDK `managementListTransactions`. |
| Outbound delivery logs | `management_list_email_logs`, CLI `management:list-email-logs`, SDK `managementListEmailLogs`. |
| One outbound log | `management_get_email_log`, CLI `management:get-email-log`, SDK `managementGetEmailLog`. |
| Delivery metrics | `management_get_email_metrics`, CLI `management:get-email-metrics`, SDK `managementGetEmailMetrics`. |
| Incoming logs | CLI `management:list-inbox-logs` / `management:get-inbox-log`, SDK `managementListInboxLogs` / `managementGetInboxLog`. |
CLI:
```bash
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:get-spend-summary \
--query days=30 \
--json
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:list-email-logs \
--query status=failed \
--query limit=20 \
--json
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux management:get-email-log \
--path public_id=dlog_abc \
--header If-None-Match="$ETAG" \
--json
```
## Routing
- First setup/auth check: `sendmux-getting-started`.
- Single or batch transactional sending: `sendmux-send-email`.
- Mailbox read, search, sync, triage, or reply: `sendmux-mailbox-agent`.
- CLI command details: `sendmux-cli`.
- MCP connection setup: `sendmux-mcp-setup`.
- Cheapest-call doctrine: `sendmux-token-efficient-usage`.