sendmux-management

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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({

From Sendmux/skills, Apache-2.0.

More from Sendmux/skills