Outcome
Create a hosted mailbox or an external mailbox connection record in the selected workspace.
Before you start
- Verify the intended environment, credential and authorized organization context before discovery.
- Discover Mail, the exact action and its mailboxes:manage permission. Pass the accessible workspace resource binding separately from action input.
- Review the actual change, recipients, provider/AI costs and any irreversible effects before confirmation; fixture IDs authorize no live operation.
Discover the target
- Run credential-scoped Mail discovery and topolo workspaces list topolo-mail; select an authorized canonical workspace.
- Resolve mailbox IDs through mailboxes.collection.list in that workspace. Resolve message, draft, thread, folder and scheduled IDs through the related published reads; never reuse fixture IDs or another context.
topolo whoami --json
topolo apps get topolo-mail --json
topolo actions get app_topolo_mail.mailboxes.create --json
topolo workspaces list topolo-mail --json
Request
Create payload.json using the current input schema and discovered identifiers. Plan the unchanged request before execution.
topolo actions validate app_topolo_mail.mailboxes.create --data @payload.json --json
topolo actions plan app_topolo_mail.mailboxes.create --resource-type workspace --resource-id <discovered-workspace-id> --data @payload.json --confirm --json
topolo actions call app_topolo_mail.mailboxes.create --resource-type workspace --resource-id <discovered-workspace-id> --data @payload.json --confirm --json
For MCP, use topolo_get_action, topolo_validate_action and topolo_plan_action; execute with topolo_call_action with confirm:true only after approval. Pass resourceType workspace and the discovered resourceId separately from input. An absent service/action or non-executable plan blocks that operation.
Input fields
| Field | Required | Meaning |
|---|---|---|
connectionType | Yes | topolo_hosted, imap, gmail or graph. External connections require management rights and provider-specific setup. |
address | No | Proposed hosted address/local part for availability or hosted creation. Use the normalized address and current configured domain. |
displayName | No | Non-empty display label for the mailbox; hosted creation derives one when omitted. |
fromName | No | Optional sender display name stored in mailbox settings. |
replyToAddress | No | Optional Reply-To address restricted to the mailbox domain. |
agentPrompt | No | Optional mailbox assistant instructions; setting it persists the profile and queues propagation to the mailbox. |
outboundProfileId | No | Optional outbound profile ID; no profile discovery action is declared by Mail. Use only an independently published, authorized profile ID. |
authUsername | No | IMAP account email/username; the IMAP handler uses this as the mailbox address. |
authPassword | No | IMAP app password supplied through a protected credential path; never place it in a guide, tracked payload or log. |
imapHost | No | IMAP server hostname for an explicitly approved external account. |
smtpHost | No | SMTP server hostname for that account. |
imapPort | No | Optional integer; handler default is 993. The schema has no TCP-port-range constraint, so confirm the provider-approved port. |
smtpPort | No | Optional integer; handler default is 587. Confirm the provider-approved port. |
imapSecure | No | IMAP TLS choice; the handler defaults to true unless explicitly false. |
smtpSecure | No | SMTP implicit TLS choice; the handler uses true only when explicitly true. |
Effects
- Creates and protects a mailbox profile. External modes may persist IMAP credentials or prepare a provider consent URL.
- No email is sent by creation; an external mailbox is usable only after its connection is verified.
Interpret the response
HTTP 201 returns data.mailbox and data.oauth. Hosted creation needs a valid available address. IMAP uses authUsername, authPassword and both host pairs; missing ports default to IMAP 993 and SMTP 587 in the handler. Gmail/graph start as pending_oauth. HTTP 201 with oauth:null and error means a mailbox record exists but OAuth URL generation failed; it does not authorize duplicate creation. The retained successful capture covers hosted creation; external authorization and credential persistence remain controlled ports.
Worked requests and responses
Successful fixture request · HTTP 201
Input
{
"connectionType": "topolo_hosted",
"address": "synthetic-fixture"
}
SDK response or error
{
"success": true,
"data": {
"mailbox": {
"id": "mbx_000000000000400080000000",
"organizationId": "org_mail_fixture",
"workspaceId": "ws_mail_fixture",
"userId": "usr_mail_fixture",
"organizationSlug": null,
"address": "synthetic-fixture@topolo.app",
"displayName": "Synthetic Fixture",
"fromName": null,
"replyToAddress": null,
"status": "active",
"agentPrompt": null,
"outboundProfileId": null,
"connectionType": "topolo_hosted",
"connectionStatus": "active",
"connectionStatusReason": null,
"providerIdentity": null,
"lastSyncAt": null,
"createdAt": "2026-10-08T00:00:00.000Z",
"updatedAt": "2026-10-08T00:00:00.000Z"
},
"oauth": null
}
}
Refused requests
Unauthenticated caller · HTTP 401
Input
{
"connectionType": "topolo_hosted",
"address": "synthetic-fixture"
}
SDK response or error
{
"code": "auth_error",
"status": 401,
"message": "Fixture authentication refused"
}
Service HTTP body
{
"success": false,
"error": {
"message": "Fixture authentication refused"
}
}
Permission denied · HTTP 403
Input
{
"connectionType": "topolo_hosted",
"address": "synthetic-fixture"
}
SDK response or error
{
"code": "permission_denied",
"status": 403,
"message": "TopoloMail permission denied"
}
Service HTTP body
{
"success": false,
"error": {
"message": "TopoloMail permission denied"
}
}
Verify the result
- Retain data.mailbox.id; read mailboxes.get and connections.get in the same workspace. For external modes, complete the explicitly approved provider consent and confirm active connection state.
- On an uncertain create result, list mailboxes and reconcile the normalized address before another creation.
Recover
Inspect the returned or rediscovered mailbox before retrying. Removing a created mailbox is a separate irreversible mailboxes.delete operation requiring reviewed export and deletion approval; it is not an automatic rollback.
- HTTP 401
auth_error: Authenticate again in the intended environment and context, then repeat identity and action discovery. - HTTP 403
permission_denied: Stop for the exact permission, organization, sender or Reply-To refusal. Do not broaden access or switch credentials automatically.
The captured SDK errors preserve the service code when structured, otherwise http_error and HTTP status. Do not invent a more specific code. Preserve the live request ID and inspect actual diagnostics for uncaptured failures.
Related actions
Evidence and limits
-
Actual exported Mail handler dispatcher, widget handler, domain handlers, SDK transport/projection and shipped SQLite control/delivery/tracking migrations.
-
Identity, permissions, verified workspace grants, provider connection state, OAuth URL generation, mailbox Durable Object operations and content protection are synthetic ports.
-
Nexus AI and Auth archive are allowlisted in-process responses. No paid generation, billing, live OAuth, encryption custody, email delivery, asynchronous delivery or deployed outcome is proved. External network egress is refused.
The captured requests use synthetic identities and .test recipients. They demonstrate handler and SDK response behavior; they do not authorize delivery, provider consent, paid generation, deletion or other live effects. Current catalog discovery and environment proof remain separate release requirements.