Sendmux Management

Sendmux management

Use this skill for team administration with an smx_root_ key.

Boundaries

• Do not ask the user to paste an API key or one-time secret.
• Use smx_root_ keys for Management API calls.
• 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

For terminal work, use the sendmux CLI with --json. For application code, use @sendmux/management and createManagementClient.

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.

MCP tools:

CLI:

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:

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

Create mailboxes with a root key; use mailbox keys afterwards for agent mailbox work.

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.

MCP tools:

CLI:

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"}' \
  --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:

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

MCP covers the common create-and-test path:

Use CLI or SDK for full lifecycle work:

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.

CLI:

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.