Agent Self Registration: APIs, Tokens and Tests

Sendmux TeamSep 10, 202612m

Agent self registration in Sendmux creates an inbox on @myagent.mx and a durable credential for reading and receiving mail. The current flow does not require the agent to solve a challenge or exchange a claim token. Sending remains unavailable until an owner accepts an invitation and explicitly approves it; the agent then obtains a separate one-hour Sending token.

Required capabilities

Registration steps

Credentials

Mailbox operations

Events

Testing

Security

Owner approval

Sendmux integration

Further reading

What does agent self registration need?

For a Sendmux integration, plan for mailbox state, inbound notifications, credential handling, sending controls and tenant limits. These capabilities support the agent after registration, rather than proving that registration alone makes a system secure or scalable. Keep the responsibilities visible when deciding what the agent, your application and the email provider will each manage.

Persistent mailbox data. Retrieve message history, threads and folders when needed instead of treating a notification as the only copy of a message.

An inbound notification path. Use SSE for a connected client or signed webhooks for an endpoint that can receive event requests, with recovery appropriate to each path.

Scoped, revocable credentials. Keep the durable inbox credential separate from temporary Sending access and from account-level management keys.

Sending routes and quotas. Use only the providers and limits permitted for the authenticated credential and sender; approval does not override those controls.

Tenant and storage boundaries. Map each agent to its authorised mailbox and monitor applicable storage and resource limits. Verify access boundaries instead of assuming mailbox count proves isolation.

How does registration work step by step?

Start from the current Agent Access service document. Use the Sendmux CLI when available: it saves the credential in a private profile and avoids printing it. The HTTP flow is the documented fallback. Discovery, registration, invitation and Sending access are separate stages, so save enough state to resume each one safely.

sendmux agent:register <profile> --owner-email owner@example.com

Discover the current contract. Read the service metadata and the API resources it names. Do not infer today's flow from an older proof-of-work or pre-claim example.

Persist the registration intent. For HTTP registration, generate and save Idempotency-Key before the first request. Submit the anonymous registration request to POST /agent-auth/agent/identity with the intended mailbox local part and client name.

Save the durable credential. Store the returned access_token securely alongside the registration ID and mailbox identity. It has mailbox.read and email.receive, without email.send.

Wait for mailbox readiness. Use the credential for mailbox access. A provisioning response does not mean the token is invalid; honour the endpoint's retry guidance and keep the existing registration.

Invite the owner. The durable token can call the owner invitation endpoint. The owner must accept the invite and separately approve Sending access; a pending invitation is not approval.

Obtain Sending access when needed. Exchange the durable token for a separate Sending-resource token with email.send. Cache that token only until its expiry; retain the durable read credential for later access and exchanges.

The Agent Access guide describes the recovery boundary: replaying the same registration key and body within 24 hours returns the same raw token without another inbox allocation. After that reveal window, it cannot reveal the token again. The durable token itself does not expire on that timer. Save it immediately rather than relying on replay as long-term secret storage.

Test lost responses, unchanged retries, conflicting requests and a registration that remains read-only while approval is pending. An accepted exchange can create a new temporary Sending token, so do not treat every concurrent exchange as a forbidden claim collision. Keep integration reliability separate from claims about automation productivity: an uneventful happy path does not establish how recovery behaves.

Two agent credentials: retain the durable read-and-receive token; after owner acceptance and explicit Sending approval, exchange for a separate one-hour Sending token. Full registration revocation ends both.

Which credentials should an agent hold?

Choose credentials by their resource and granted permissions. Sendmux has several credential roles, and a prefix alone does not establish which API an agent may use. In particular, smx_mbx_ can identify a standalone Sending key or a mailbox key; smx_agent_ can identify the durable read credential or a separate Sending token.

Credential role	Intended access	Boundary to verify
Infrastructure key, `smx_root_`	Granted team-level Management operations	Direct Mailbox API requests reject it; management powers still need protection
Standalone Sending key, `smx_mbx_`	Permitted outbound sending	It does not automatically represent a readable mailbox
Mailbox key, `smx_mbx_`	One mailbox with granted permissions	Mailbox credentials can also serve as its SMTP and IMAP password
Agent token, `smx_agent_`	Its specific resource and scopes	Durable read access and temporary Sending access are separate credentials

Mailbox permission names include mailbox.read, email.receive, email.send and mailbox.settings.update. Give an agent only what its workflow requires. Rejecting an infrastructure key directly at a Mailbox endpoint does not prove that a compromised management credential could never affect mailbox resources or credential provisioning. Keep account-level credentials out of a mailbox-only integration.

Owner approval enables the separate Sending grant; it does not add sending permission to the original read token. An agent can read incoming messages and prepare proposed replies in your application while Sending remains unavailable. Log grant and revocation events without logging raw secrets, and distinguish a legitimate new Sending token from an unexpected permission change.

Plan for revocation as well as expiry. Revoking Sending access leaves the durable inbox credential in place; revoking the complete registration removes both read and send access. Treat durable secrets as long-lived credentials that need protection. Do not design a periodic re-assertion loop around a pre-claim expiry that the current flow does not use.

Which mailbox operations support agent work?

Use the Mailbox API to retrieve the state and content the authorised agent needs. A capability response tells you what is available, but each operation still requires the right scope. The durable read credential does not grant every mailbox write or management action listed below.

Session and state. GET /mailbox/session reports capabilities, limits and state tokens before the client chooses its next operation.

Filtered retrieval. Message queries can narrow results by supported folder, thread, text, sender, subject, header, date and unread filters. Validate the actual query parameters rather than constructing an assumed filter language.

Counts and snippets. Count and search-snippet operations avoid fetching complete bodies when the application only needs a total or preview.

Batch and sync. Batch get, update and delete operate under their documented limits and permissions. State tokens and change endpoints support incremental synchronisation instead of repeated full listings.

Attachments. Use upload/download references or short-lived links and check size limits. Attachment metadata does not mean an attachment's contents have been parsed.

Administrative controls. Authorised management can suspend inbound mail, sending, Mailbox API access, SMTP and IMAP, then resume access without deleting the mailbox's stored messages.

The clean content endpoint returns body content and processing metadata, including controls for quoted history and signatures. Use the documented body.text, truncation and stripping indicators; do not assume an extracted_text field or perfect removal of every quoted reply. Retrieve additional content when a truncated result is insufficient, and treat both messages and attachments as untrusted input.

Inbound sender rules can exist at domain and mailbox level. Each scope uses allow or block rules, not both simultaneously; mailbox rules take precedence over domain rules when present. This is different from saying domain and mailbox rules cannot coexist. These rules govern inbound senders, so they do not establish an outbound recipient suppression policy.

How do SSE and webhooks differ?

SSE keeps a client connection open for live inbound notifications. Webhooks send signed HTTP requests to a configured endpoint and can cover inbound and outbound events. They have different event coverage and recovery contracts; neither promises that every event reaches an agent immediately or that no state reconciliation will be needed.

For mailbox SSE, the native mail events are message.received and message.received.spam. Resume using Last-Event-ID or the documented query parameter. If the stream returns sync_required, call the change endpoint before reconnecting. Received events include a capped body snapshot and attachment metadata, so fetch full content or bytes through the relevant endpoints when required.

Webhook event types include message.delivered, message.bounced, message.complained, message.rejected, message.delivery_delayed, message.received and message.received.spam. A delivered event records recipient-system acceptance, not guaranteed inbox placement. Preserve those distinctions in your event handler instead of mapping every outcome to one generic failure or success state.

Verify X-Sendmux-Signature using the documented HMAC-SHA256 procedure over the raw request body, and deduplicate event IDs separately. Retryable webhook failures use backoff within the documented window. Delivery metadata and retained payloads are available for seven days. That retention window is different from SSE replay or mailbox storage.

How should you test self-registration?

Test the complete authorised workflow as well as its denial paths. A local test suite can exercise decisions; it does not prove that a production registration, invitation or email send occurred. When performing a live check, use explicitly authorised accounts and controlled recipients, retain the identifiers and verify each observed outcome.

Registration and recovery. Check a new registration, lost-response replay with the same key/body, a conflicting request and an unavailable mailbox name. Confirm the original durable token remains usable after its reveal window.

Approval and scope. Check reading before approval, rejection of Sending access while approval is pending, owner acceptance without Sending approval, and the separate Sending token after approval. Verify the durable token still cannot send.

Expiry and revocation. Test an expired Sending token, Sending-only revocation and complete registration revocation. Do not use an invented expiring pre-claim token as the primary current-flow test.

Events and mailbox state. Exercise SSE reconnection and required synchronisation, invalid webhook signatures, duplicate events, truncated content, missing attachments and applicable mailbox limits.

Sending controls. Test denied sender or mailbox access, exhausted quotas and provider failures within the allowed route. An asynchronous acceptance is not proof of delivery, and retries must retain the original sending intent.

Use the current OpenAPI 3.1 contracts and the documented SDKs for TypeScript, Python, Go, PHP, Ruby or Rust. Pin the versions and test the API surface you actually use; generated clients do not guarantee identical runtime behaviour across languages. Include the CLI profile's secret handling and persistence when it is part of your deployment.

If the integration uses MCP or A2A, test discovery and the advertised OAuth flow separately. Their audiences and selected grants matter. Discovering hosted tools does not automatically register an inbox or make a token valid for a different resource.

Which onboarding security controls matter?

Protect retrievable credentials in a managed secret store, restrict access and avoid putting them in logs, prompts, screenshots or source files. Use verified secure transport and follow the credential's documented lifecycle. A named hashing or encryption algorithm is not a substitute for checking who can retrieve, use or revoke a secret.

Bind mailbox and tenant context to authenticated permissions. Apply the actual credential, mailbox, account and provider limits rather than assuming all rate limits are per credential. Review unusual grant changes and sending patterns, but do not infer that one signal proves compromise. Keep a documented way to pause affected access while an owner investigates.

Treat inbound mail as data, not authority. Receiving an instruction does not authorise an agent to run commands, disclose a token or change configuration. Owner approval for Sending also does not approve every recipient or message the agent might propose. Keep those application-level decisions explicit and independently testable.

What does owner approval change?

Owner acceptance and explicit Sending approval allow the agent to obtain a separate temporary Sending credential. They leave the durable read token unchanged. This gives an owner a decision point before sending is enabled, while an agent can already receive and inspect mail. It is an access-control boundary, not proof that the agent's future behaviour is safe.

Persistence, filtered retrieval and clean-content controls can reduce unnecessary processing when used appropriately. Measure that effect in the actual workflow rather than promising lower model cost or better reasoning. Provider routing and quotas also need their own review: connecting another provider does not guarantee reputation isolation or remove safety restrictions.

Where does Sendmux fit?

Sendmux combines persistent agent inboxes, scoped access and outbound sending. Anonymous self-registration uses @myagent.mx; custom-domain mailboxes require the appropriate verified domain and provisioning workflow. Shared-domain mailbox sending uses the managed route. Other sending credentials or custom-domain mailboxes can use permitted connected providers and delivery groups, subject to their configured scope and quotas.

Check the current billing rules when planning capacity. Billing includes the applicable plan base, billable email usage and storage; outgoing usage counts provider-accepted recipient occurrences, while inbound usage counts distinct mailbox deliveries. It is not simply a promise to pay only when a message is sent or received, and provider quotas and safety controls still apply.

Start with the documented CLI registration or HTTP fallback, confirm mailbox readiness, then verify the owner approval and token boundaries in an authorised test. Keep that evidence separate from SDK installation, a successful unit test or an API response that only accepted work for processing. Each proves a different part of the integration.

Frequently Asked Questions

What is agent self registration?

Agent self registration is an automated way for a software agent to obtain an inbox and scoped access. In the current Sendmux flow, anonymous registration creates an @myagent.mx mailbox and a durable read-and-receive token. Persist the registration key before requesting it and save the returned credential securely. Sending requires separate owner acceptance and explicit approval.

Can a self-registered agent send email immediately?

No. The durable token grants mailbox.read and email.receive, without email.send. The owner must accept the invitation and explicitly approve Sending access before the agent can exchange for a separate Sending-resource token. That token lasts one hour; the original read credential remains unchanged. Approval also does not override sender, quota or provider restrictions.

What happens if a pre-claim token expires before owner approval?

The current Sendmux registration flow uses a durable read-and-receive token, rather than an expiring pre-claim token. Its 24-hour reveal window limits recovery of the same raw token through an unchanged registration retry; it is not the credential lifetime. Save the token immediately. After owner approval, obtain a separate one-hour Sending token when needed. Complete registration revocation removes both forms of access.

Does Sendmux support automated agent onboarding without a human?

Initial anonymous registration and read access can be automated without owner approval. The current flow uses a persisted Idempotency-Key and creates an @myagent.mx mailbox; it does not require the older challenge-and-claim sequence. Sending still requires owner acceptance and explicit Sending approval. Custom-domain mailboxes use the appropriate verified-domain provisioning workflow, so do not assume anonymous registration configures customer DNS.

Which is better for real-time inbound mail, SSE or webhooks?

Use SSE for a connected client that wants inbound notifications, or webhooks when you can receive signed HTTP requests. Native mailbox SSE covers message.received and message.received.spam, with replay and synchronisation handling. Webhooks cover additional delivery outcomes and have their own signature, retry and retention contract. Choose using event coverage and recovery requirements; the two transports are not interchangeable.