diff --git a/changelog.mdx b/changelog.mdx index 9791fda..bf768da 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -4,6 +4,15 @@ description: "New features, improvements, and fixes across the Sendmux platform. rss: true --- + + ## Agent access + +Agents can now discover Sendmux through `auth.md`, create an agent-managed team with one free `@myagent.mx` mailbox, and invite a verified human owner. + +Pre-claim agent tokens can read mailbox data and receive mail, but they cannot send mail until a human claims the team. + + + ## Hosted MCP diff --git a/cli/index.mdx b/cli/index.mdx index a45acfc..6c8885c 100644 --- a/cli/index.mdx +++ b/cli/index.mdx @@ -16,8 +16,9 @@ keywords: Use the `sendmux` CLI when you want terminal access to the same Management, Mailbox, and Sending API surfaces exposed by the SDKs. - Sending and Mailbox commands require mailbox-scoped `smx_mbx_` keys. - Management commands require team-scoped `smx_root_` keys. + Sending and Mailbox commands accept mailbox-compatible `smx_mbx_` keys or + scoped `smx_agent_` tokens. Management commands require team-scoped + `smx_root_` keys. ## Install @@ -74,7 +75,7 @@ Every API command resolves credentials in this order: `--base-url` overrides the API base URL for one command. `SENDMUX_BASE_URL` overrides it for the current shell. A profile can also store a base URL override. -Before running the API call, the CLI checks that the key prefix matches the command surface. A management command fails early when it receives a mailbox key, and mailbox or sending commands fail early when they receive a root key. +Before running the API call, the CLI checks that the key prefix matches the command surface. A management command fails early when it receives a mailbox-compatible key, and mailbox or sending commands fail early when they receive a root key. API permissions still apply, so a pre-claim `smx_agent_` token cannot send email. ## Run commands diff --git a/docs.json b/docs.json index f4697ab..5878354 100644 --- a/docs.json +++ b/docs.json @@ -60,7 +60,12 @@ { "group": "AI integrations", "icon": "robot", - "pages": ["guides/agent-skills", "guides/mcp", "guides/mcp-clients"] + "pages": [ + "guides/agent-access", + "guides/agent-skills", + "guides/mcp", + "guides/mcp-clients" + ] }, { "group": "Teams and access", diff --git a/guides/agent-access.mdx b/guides/agent-access.mdx new file mode 100644 index 0000000..981c878 --- /dev/null +++ b/guides/agent-access.mdx @@ -0,0 +1,174 @@ +--- +title: "Agent access" +description: "Let an AI agent register a constrained Sendmux mailbox, get a short-lived agent token, and invite its human owner." +keywords: + [ + "agent access", + "auth.md", + "AI agents", + "agent mailbox", + "smx_agent", + "owner invite", + ] +--- + +Agent access lets an AI agent start with one constrained `@myagent.mx` mailbox before a person joins the team. The agent can read and receive mail for that mailbox, then ask Sendmux to invite the human owner. + + + Pre-claim agent tokens include `mailbox.read` and `email.receive`. They do + not include `email.send`. + + +## How it works + +1. Discover Sendmux at `https://app.sendmux.ai/auth.md`. +2. Create an anonymous agent identity. +3. Exchange the returned identity assertion for an `smx_agent_` access token. +4. Use the token as a Bearer token for allowed Mailbox API calls. +5. Ask Sendmux to send the owner invite. +6. After the owner accepts, use normal team credentials and limits. + +Sendmux sends the owner invite email through the invite system. The agent does not need Sending API access to invite its owner. + +## Discovery + +Agents can read the human-readable service document first. + +```bash +curl https://app.sendmux.ai/auth.md +``` + +API discovery also starts from the protected-resource metadata URL: + +```text +https://app.sendmux.ai/.well-known/oauth-protected-resource/api/v1 +``` + +The authorisation-server metadata advertises the token and revocation endpoints. Its `agent_auth` block names the identity and invite endpoints: + +```text +https://app.sendmux.ai/.well-known/oauth-authorization-server/agent-auth +``` + +## Register an agent identity + +Call the identity endpoint without an existing API key. + +```bash +curl -X POST https://app.sendmux.ai/agent-auth/agent/identity \ + -H "Content-Type: application/json" \ + -d '{ + "type": "anonymous", + "mailbox_local_part": "triage-agent", + "client_name": "Triage Agent", + "idempotency_key": "agent-register-001" + }' +``` + +The response includes an identity assertion and the assigned mailbox. + +```json +{ + "registration_id": "areg_abc123", + "registration_type": "anonymous", + "identity_assertion": "eyJ...", + "assertion_expires": "2026-06-18T04:15:00.000Z", + "pre_claim_scopes": ["mailbox.read", "email.receive"], + "mailbox": { + "email": "triage-agent@myagent.mx", + "status": "provisioning" + } +} +``` + +## Exchange the assertion + +Use the OAuth JWT bearer grant to get an `smx_agent_` access token. + +```bash +curl -X POST https://app.sendmux.ai/agent-auth/oauth2/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \ + --data-urlencode "assertion=$SENDMUX_AGENT_IDENTITY_ASSERTION" \ + --data-urlencode "resource=https://app.sendmux.ai/api/v1" +``` + +If the mailbox is still being prepared, the token endpoint returns `temporarily_unavailable` with `Retry-After`. + +```json +{ + "access_token": "smx_agent_...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "mailbox.read email.receive" +} +``` + +## Use the mailbox + +Pass the `smx_agent_` token as a Bearer token to allowed Mailbox API endpoints. + +```bash +curl https://app.sendmux.ai/api/v1/mailbox/me \ + -H "Authorization: Bearer smx_agent_your_token_here" +``` + +The token is mailbox-compatible, but permissions still apply. A pre-claim token can read and receive mail. It cannot send through the Mailbox API or Sending API. + +## Invite the owner + +Ask Sendmux to invite the human owner. + +```bash +curl -X POST https://app.sendmux.ai/agent-auth/agent/identity/invite \ + -H "Authorization: Bearer smx_agent_your_token_here" \ + -H "Content-Type: application/json" \ + -d '{ + "email": "owner@example.com", + "requested_role": "owner", + "idempotency_key": "owner-invite-001" + }' +``` + +The response only confirms the invite request. + +```json +{ + "invite_id": "ainv_abc123", + "status": "pending" +} +``` + +The invite email goes to the owner. Membership starts only after that person verifies and accepts the invite. One live pre-claim owner invite can be pending per registration; retry the same request with the same `idempotency_key`. + +## Revoke a token + +Revoke an agent access token when it is no longer needed. + +```bash +curl -X POST https://app.sendmux.ai/agent-auth/oauth2/revoke \ + -H "Content-Type: application/x-www-form-urlencoded" \ + --data-urlencode "token=$SENDMUX_AGENT_ACCESS_TOKEN" \ + --data-urlencode "token_type_hint=access_token" +``` + +## Limits + +Each anonymous registration gets exactly one constrained `@myagent.mx` mailbox. Unclaimed registrations expire after 24 hours. After the owner accepts the invite, the team uses normal Sendmux limits and can request increases like any other team. + +## Next steps + + + + Read and sync mailbox data with an agent token. + + + Teach AI coding tools the Sendmux agent workflows. + + + Use SDK clients with mailbox-compatible tokens. + + + Review manual keys, connected apps, and agent tokens. + + diff --git a/guides/agent-skills.mdx b/guides/agent-skills.mdx index e15546a..a699054 100644 --- a/guides/agent-skills.mdx +++ b/guides/agent-skills.mdx @@ -17,8 +17,9 @@ keywords: Sendmux Agent Skills teach AI coding tools how to send email, read mailboxes, manage team resources, and choose low-token Sendmux calls. Use them when your agent needs Sendmux context before it writes commands, API calls, or integration code. - Skills do not grant Sendmux access by themselves. Create API keys or authorise - Product MCP separately, then let the skill choose the right surface for the task. + Skills do not grant Sendmux access by themselves. Create API keys, authorise + Product MCP, or use agent access first, then let the skill choose the right + surface for the task. ## Install @@ -66,7 +67,7 @@ Claude.ai and Claude Desktop do not use `skills add`. Upload a zipped individual | `sendmux-cli` | Running Sendmux commands from a terminal. | | `sendmux-mcp-setup` | Connecting Sendmux MCP servers to an agent client. | | `sendmux-token-efficient-usage` | Choosing low-token calls such as batch sends, counts, snippets, deltas, cursors, and conditional requests. | -| `sendmux-email-for-agents` | Giving an AI agent an inbox, a send-receive workflow, or a human-approved draft flow. | +| `sendmux-email-for-agents` | Giving an AI agent an inbox, a self-registration flow, or a human-approved send workflow. | ## Choose the right surface @@ -77,7 +78,7 @@ Claude.ai and Claude Desktop do not use `skills add`. Upload a zipped individual | Application code | Use an SDK package. | | Endpoint detail or uncommon operation | Use the API reference. | -Use mailbox-scoped `smx_mbx_` keys for Sending and Mailbox work. Use team-scoped `smx_root_` keys for Management work. +Use mailbox-scoped `smx_mbx_` keys for Sending and Mailbox work. Use team-scoped `smx_root_` keys for Management work. Self-registered agents can also use `smx_agent_` tokens for their allowed Mailbox API work. Pre-claim `smx_agent_` tokens do not include `email.send`. ## Next steps @@ -85,6 +86,9 @@ Use mailbox-scoped `smx_mbx_` keys for Sending and Mailbox work. Use team-scoped Connect hosted or local Sendmux MCP tools. + + Let an agent register a constrained mailbox and invite its owner. + Run Sendmux workflows from your terminal. diff --git a/guides/api-keys.mdx b/guides/api-keys.mdx index 2e3ffef..249b021 100644 --- a/guides/api-keys.mdx +++ b/guides/api-keys.mdx @@ -23,6 +23,7 @@ Connected apps are different. They appear on the same credentials page for manag | --- | --- | --- | --- | | **Manual API key** | A team member creates a key in Sendmux. | Long-lived until you rotate or revoke it. | **API Keys** with the **Manual keys** filter. | | **Connected app** | You authorise an app through OAuth, such as Product MCP. | 15-minute access tokens with rotating refresh tokens. | **API Keys** with the **Connected apps** filter. | +| **Agent access token** | An agent registers through agent access. | Short-lived access token. | Agent access flow, then normal team controls after owner acceptance. | Revoking a manual API key stops that key. Disconnecting a connected app stops that app refreshing access and using its existing connection. @@ -33,9 +34,12 @@ Revoking a manual API key stops that key. Disconnecting a connected app stops th | **Infrastructure key** | Team automation, providers, routing, billing, logs, domains, mailboxes, and webhooks. | `smx_root_` | | **Sending key** | Sending mail through the Sending API, SMTP, CLI tools, MCP clients, or agents. | `smx_mbx_` | | **Mailbox key** | API, IMAP, and SMTP access for one mailbox. | `smx_mbx_` | +| **Agent token** | Constrained mailbox access for a self-registered agent. | `smx_agent_` | Sending keys and mailbox keys share the `smx_mbx_` prefix. Their permissions and sending scope decide what each key can do. +Pre-claim agent tokens include `mailbox.read` and `email.receive`, not `email.send`. The agent can ask Sendmux to invite the owner through [agent access](/guides/agent-access). + Each team starts with **100 active credentials** across manual API keys and connected apps. See [Team limits](/guides/team-limits). diff --git a/guides/mcp-clients.mdx b/guides/mcp-clients.mdx index 069935e..163ce71 100644 --- a/guides/mcp-clients.mdx +++ b/guides/mcp-clients.mdx @@ -67,7 +67,9 @@ Use this page to connect Sendmux Product MCP to your AI client. Prefer hosted OA stdio if the client can launch commands, or private HTTP if it needs a URL. -## Hosted OAuth clients + + +## Hosted OAuth clients (Recommended) Use the hosted endpoint when the client supports remote MCP OAuth: diff --git a/mailbox-api/introduction.mdx b/mailbox-api/introduction.mdx index 837efe0..527ea05 100644 --- a/mailbox-api/introduction.mdx +++ b/mailbox-api/introduction.mdx @@ -28,14 +28,14 @@ https://app.sendmux.ai/api/v1 ## Authentication -Authenticate with a mailbox credential or connected-app access token from the Sendmux app. Pass it as a Bearer token in the `Authorization` header. +Authenticate with a mailbox credential, connected-app access token, or agent access token from Sendmux. Pass it as a Bearer token in the `Authorization` header. ```bash curl https://app.sendmux.ai/api/v1/mailbox/me \ -H "Authorization: Bearer smx_mbx_your_key_here" ``` -Manual mailbox credentials are scoped to one mailbox. The same credential is also accepted as the mailbox password for SMTP submission and IMAP retrieval. Connected-app tokens can be granted one or more mailboxes, and each mailbox request is limited to that granted set. Root API keys are rejected on Mailbox API endpoints. +Manual mailbox credentials are scoped to one mailbox. The same credential is also accepted as the mailbox password for SMTP submission and IMAP retrieval. Connected-app tokens can be granted one or more mailboxes, and each mailbox request is limited to that granted set. Agent access tokens use the `smx_agent_` prefix and are limited by their granted scopes. Root API keys are rejected on Mailbox API endpoints. ## Current endpoints @@ -90,6 +90,8 @@ Manual mailbox credentials always target their single mailbox. Omit `mailbox_id` Connected-app tokens can grant a set of mailboxes. Use `GET /mailbox/mailboxes` to list or search the granted set, then pass the selected mailbox's `id` as `mailbox_id` on Mailbox API requests. +Self-registered agent tokens target their assigned mailbox. Omit `mailbox_id` when you use a pre-claim `smx_agent_` token. Pre-claim tokens can read and receive mail, but they cannot send. + ```bash curl "https://app.sendmux.ai/api/v1/mailbox/mailboxes?q=support" \ -H "Authorization: Bearer connected_app_access_token" diff --git a/sdks/go.mdx b/sdks/go.mdx index 8d7e26f..16c44c0 100644 --- a/sdks/go.mdx +++ b/sdks/go.mdx @@ -15,8 +15,9 @@ keywords: Use the Go SDK when your application needs importable clients for the Sending, Mailbox, or Management API. - Sending and Mailbox clients require mailbox-scoped `smx_mbx_` keys. - Management clients require team-scoped `smx_root_` keys. + Sending and Mailbox clients accept mailbox-compatible `smx_mbx_` keys or + scoped `smx_agent_` tokens. Management clients require team-scoped + `smx_root_` keys. ## Requirements @@ -104,10 +105,15 @@ func main() { | Surface | Import path | Factory | API key | | --- | --- | --- | --- | -| Sending | `sendmux.ai/go/sending` | `sending.New` | `smx_mbx_` | -| Mailbox | `sendmux.ai/go/mailbox` | `mailbox.New` | `smx_mbx_` | +| Sending | `sendmux.ai/go/sending` | `sending.New` | `smx_mbx_` or scoped `smx_agent_` | +| Mailbox | `sendmux.ai/go/mailbox` | `mailbox.New` | `smx_mbx_` or scoped `smx_agent_` | | Management | `sendmux.ai/go/management` | `management.New` | `smx_root_` | + + The SDK accepts `smx_agent_` on mailbox-compatible clients, but the API still + enforces endpoint permissions. Pre-claim agent tokens cannot send email. + + Sending uses `https://smtp.sendmux.ai/api/v1` by default. Mailbox and Management use `https://app.sendmux.ai/api/v1`. ## Shared API behaviour diff --git a/sdks/index.mdx b/sdks/index.mdx index 1e600e0..3d76d62 100644 --- a/sdks/index.mdx +++ b/sdks/index.mdx @@ -21,19 +21,24 @@ Sendmux SDKs give your application package-managed clients for the Sending, Mail Use an umbrella package when one application needs more than one API surface. Use a surface package when you want a smaller dependency for one job. - Create the API key in Sendmux before you install a package. Sending and - Mailbox clients use mailbox-scoped `smx_mbx_` keys. Management clients use - team-scoped `smx_root_` keys. + Create the credential in Sendmux before you install a package. Sending and + Mailbox clients accept mailbox-compatible `smx_mbx_` keys or scoped + `smx_agent_` tokens. Management clients use team-scoped `smx_root_` keys. ## Choose a surface | Surface | Use it for | API key | | --- | --- | --- | -| Sending | Send single or batch emails. | `smx_mbx_` | -| Mailbox | Read, search, organise, and send from a mailbox. | `smx_mbx_` | +| Sending | Send single or batch emails. | `smx_mbx_` or scoped `smx_agent_` | +| Mailbox | Read, search, organise, and send from a mailbox. | `smx_mbx_` or scoped `smx_agent_` | | Management | Manage team resources such as domains, sending accounts, mailboxes, webhooks, logs, metrics, and billing data. | `smx_root_` | + + SDK prefix validation treats `smx_agent_` as mailbox-compatible. The API still + enforces scopes. Pre-claim agent tokens do not include `email.send`. + + ## Choose a package family | Language | Umbrella package | Surface packages | diff --git a/sdks/php.mdx b/sdks/php.mdx index 254cbb8..2f5627e 100644 --- a/sdks/php.mdx +++ b/sdks/php.mdx @@ -15,8 +15,9 @@ keywords: Use the PHP SDK when your application needs Composer packages for one or more Sendmux API surfaces. - Sending and Mailbox clients require mailbox-scoped `smx_mbx_` keys. - Management clients require team-scoped `smx_root_` keys. + Sending and Mailbox clients accept mailbox-compatible `smx_mbx_` keys or + scoped `smx_agent_` tokens. Management clients require team-scoped + `smx_root_` keys. ## Requirements @@ -97,10 +98,15 @@ $mailboxes = ClientFactory::createMailboxesApi( | Surface | Package | Factory examples | API key | | --- | --- | --- | --- | -| Sending | `sendmux/sending` | `createEmailsApi`, `createMetaApi` | `smx_mbx_` | -| Mailbox | `sendmux/mailbox` | `createMailboxAPIApi` | `smx_mbx_` | +| Sending | `sendmux/sending` | `createEmailsApi`, `createMetaApi` | `smx_mbx_` or scoped `smx_agent_` | +| Mailbox | `sendmux/mailbox` | `createMailboxAPIApi` | `smx_mbx_` or scoped `smx_agent_` | | Management | `sendmux/management` | `createMailboxesApi`, `createDomainsApi`, `createWebhooksApi` | `smx_root_` | + + The SDK accepts `smx_agent_` on mailbox-compatible clients, but the API still + enforces endpoint permissions. Pre-claim agent tokens cannot send email. + + Sending uses `https://smtp.sendmux.ai/api/v1` by default. Mailbox and Management use `https://app.sendmux.ai/api/v1`. ## Shared API behaviour diff --git a/sdks/python.mdx b/sdks/python.mdx index 18d689c..c6ad7ee 100644 --- a/sdks/python.mdx +++ b/sdks/python.mdx @@ -15,8 +15,9 @@ keywords: Use the Python SDK when your application needs Sendmux API clients with API-key validation, retry handling, cursor helpers, and typed API errors. - Sending and Mailbox clients require mailbox-scoped `smx_mbx_` keys. - Management clients require team-scoped `smx_root_` keys. + Sending and Mailbox clients accept mailbox-compatible `smx_mbx_` keys or + scoped `smx_agent_` tokens. Management clients require team-scoped + `smx_root_` keys. ## Requirements @@ -89,10 +90,15 @@ Surface packages expose `create_sending_client`, `create_mailbox_client`, and `c | Surface | Package | Factory | API key | | --- | --- | --- | --- | -| Sending | `sendmux-sending` | `create_sending_client` | `smx_mbx_` | -| Mailbox | `sendmux-mailbox` | `create_mailbox_client` | `smx_mbx_` | +| Sending | `sendmux-sending` | `create_sending_client` | `smx_mbx_` or scoped `smx_agent_` | +| Mailbox | `sendmux-mailbox` | `create_mailbox_client` | `smx_mbx_` or scoped `smx_agent_` | | Management | `sendmux-management` | `create_management_client` | `smx_root_` | + + The SDK accepts `smx_agent_` on mailbox-compatible clients, but the API still + enforces endpoint permissions. Pre-claim agent tokens cannot send email. + + Sending uses `https://smtp.sendmux.ai/api/v1` by default. Mailbox and Management use `https://app.sendmux.ai/api/v1`. ## Shared API behaviour diff --git a/sdks/ruby.mdx b/sdks/ruby.mdx index fae6719..2b177eb 100644 --- a/sdks/ruby.mdx +++ b/sdks/ruby.mdx @@ -15,8 +15,9 @@ keywords: Use the Ruby SDK when your application needs gems for the Sending, Mailbox, or Management API. - Sending and Mailbox clients require mailbox-scoped `smx_mbx_` keys. - Management clients require team-scoped `smx_root_` keys. + Sending and Mailbox clients accept mailbox-compatible `smx_mbx_` keys or + scoped `smx_agent_` tokens. Management clients require team-scoped + `smx_root_` keys. ## Requirements @@ -86,10 +87,15 @@ Surface gems expose `Sendmux::Sending::Client`, `Sendmux::Mailbox::Client`, and | Surface | Gem | Client or helper | API key | | --- | --- | --- | --- | -| Sending | `sendmux-sending` | `Sendmux::SDK.sending`, `client.emails` | `smx_mbx_` | -| Mailbox | `sendmux-mailbox` | `Sendmux::SDK.mailbox`, `client.mailbox_api` | `smx_mbx_` | +| Sending | `sendmux-sending` | `Sendmux::SDK.sending`, `client.emails` | `smx_mbx_` or scoped `smx_agent_` | +| Mailbox | `sendmux-mailbox` | `Sendmux::SDK.mailbox`, `client.mailbox_api` | `smx_mbx_` or scoped `smx_agent_` | | Management | `sendmux-management` | `Sendmux::SDK.management`, `client.mailboxes` | `smx_root_` | + + The SDK accepts `smx_agent_` on mailbox-compatible clients, but the API still + enforces endpoint permissions. Pre-claim agent tokens cannot send email. + + Sending uses `https://smtp.sendmux.ai/api/v1` by default. Mailbox and Management use `https://app.sendmux.ai/api/v1`. ## Shared API behaviour diff --git a/sdks/typescript.mdx b/sdks/typescript.mdx index 0c04e1c..fb6525c 100644 --- a/sdks/typescript.mdx +++ b/sdks/typescript.mdx @@ -15,8 +15,9 @@ keywords: Use the TypeScript SDK when your application needs package-managed clients for one or more Sendmux API surfaces. - Sending and Mailbox clients require mailbox-scoped `smx_mbx_` keys. - Management clients require team-scoped `smx_root_` keys. + Sending and Mailbox clients accept mailbox-compatible `smx_mbx_` keys or + scoped `smx_agent_` tokens. Management clients require team-scoped + `smx_root_` keys. ## Requirements @@ -86,10 +87,15 @@ Surface packages expose `createSendingClient`, `createMailboxClient`, and `creat | Surface | Package | Factory | API key | | --- | --- | --- | --- | -| Sending | `@sendmux/sending` | `createSendingClient` | `smx_mbx_` | -| Mailbox | `@sendmux/mailbox` | `createMailboxClient` | `smx_mbx_` | +| Sending | `@sendmux/sending` | `createSendingClient` | `smx_mbx_` or scoped `smx_agent_` | +| Mailbox | `@sendmux/mailbox` | `createMailboxClient` | `smx_mbx_` or scoped `smx_agent_` | | Management | `@sendmux/management` | `createManagementClient` | `smx_root_` | + + The SDK accepts `smx_agent_` on mailbox-compatible clients, but the API still + enforces endpoint permissions. Pre-claim agent tokens cannot send email. + + Sending uses `https://smtp.sendmux.ai/api/v1` by default. Mailbox and Management use `https://app.sendmux.ai/api/v1`. ## Shared API behaviour diff --git a/sending-api/introduction.mdx b/sending-api/introduction.mdx index 50b1afc..60c2290 100644 --- a/sending-api/introduction.mdx +++ b/sending-api/introduction.mdx @@ -51,6 +51,12 @@ curl -X POST https://smtp.sendmux.ai/api/v1/emails/send \ API keys are scoped to a team. Create and manage keys under **Settings > API Keys** in the Sendmux app. Keys used for sending require the `email.send` permission. Send-only keys and mailbox keys use the `smx_mbx_` prefix; root keys use `smx_root_`. + + Self-registered agent tokens use the `smx_agent_` prefix, but pre-claim agent + tokens do not include `email.send`. Agents invite their owner through + [agent access](/guides/agent-access), not by calling the Sending API. + + ### Permissions | Endpoint | Required permission |