---
name: sendmux-management
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`.

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. 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 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. 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 '{"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`.