Outcome
Read the canonical widget contract and its accessible workspace roster.
Before you start
- Verify the intended environment, credential and authorized organization context before discovery.
- Discover Mail, the exact action and its messages:read permission. Pass the accessible workspace resource binding separately from action input.
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.widget.get --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.widget.get --data @payload.json --json
topolo actions plan app_topolo_mail.widget.get --resource-type workspace --resource-id <discovered-workspace-id> --data @payload.json --json
topolo actions call app_topolo_mail.widget.get --resource-type workspace --resource-id <discovered-workspace-id> --data @payload.json --json
For MCP, use topolo_get_action, topolo_validate_action and topolo_plan_action; execute with topolo_read_action. Pass resourceType workspace and the discovered resourceId separately from input. An absent service/action or non-executable plan blocks that operation.
Input fields
This action accepts an empty input object. Keep workspace context separate.
Effects
- Reads the authorized shared workspace roster and Mail database aggregate counts.
Interpret the response
The response uses the shared widget envelope at the root: success, contractVersion, appId, serviceName, generatedAt, widgets, workspace and workspaces. It is not data.widgets. Mail counts reflect stored mailbox, pending scheduled and active snooze rows; a widget count is not a delivery or inbox synchronization result.
Worked requests and responses
Successful fixture request · HTTP 200
Input
{}
SDK response or error
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_mail",
"serviceName": "Mail",
"generatedAt": "2026-10-08T00:00:00.000Z",
"widgets": [
{
"id": "mail.workspace-overview",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Mail activity",
"description": "1 mailboxes, 1 scheduled sends, and 0 snoozed messages.",
"contexts": [
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_mail_fixture",
"requiredPermissions": [
"messages:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-08T00:00:00.000Z",
"lastSuccessfulAt": "2026-10-08T00:00:00.000Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 120,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {
"heroMetricKey": "mailboxes"
}
},
"drilldowns": [],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "mail.api.widget.title",
"descriptionKey": "mail.api.widget.summary"
},
"accessibility": {
"label": "Mail mailbox, scheduled-send, and snoozed-message metrics"
},
"contribution": {
"summary": "Mailbox inventory and pending delivery work for the selected Mail workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Mail workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "mailboxes",
"label": "Mailboxes",
"description": "Mailboxes connected to the workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "scheduled",
"label": "Scheduled",
"description": "Messages scheduled and awaiting delivery.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "snoozed",
"label": "Snoozed",
"description": "Messages currently snoozed.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [
{
"key": "draft",
"label": "Draft",
"order": 0,
"terminal": false
},
{
"key": "scheduled",
"label": "Scheduled",
"order": 1,
"terminal": false
},
{
"key": "sent",
"label": "Sent",
"order": 2,
"terminal": true
}
],
"events": [
{
"key": "send_scheduled",
"label": "Send scheduled",
"description": "A message was scheduled for delivery."
},
{
"key": "message_snoozed",
"label": "Message snoozed",
"description": "A message was snoozed."
}
],
"datasets": [
{
"id": "mail_operations",
"label": "Mail operations",
"description": "Mailbox and delivery workload totals.",
"grain": "One aggregate row per selected Mail workspace.",
"metricKeys": [
"mailboxes",
"scheduled",
"snoozed"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"send_scheduled",
"message_snoozed"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table",
"funnel"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "mailboxes",
"label": "Mailboxes",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-08T00:00:00.000Z",
"end": "2026-10-08T00:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "scheduled",
"label": "Scheduled",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-08T00:00:00.000Z",
"end": "2026-10-08T00:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "snoozed",
"label": "Snoozed",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-08T00:00:00.000Z",
"end": "2026-10-08T00:00:00.000Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_mail",
"serviceName": "Mail",
"lastUpdated": "2026-10-08T00:00:00.000Z"
}
],
"workspace": {
"id": "ws_mail_fixture",
"name": "Fixture workspace"
},
"workspaces": [
{
"id": "ws_mail_fixture",
"name": "Fixture workspace",
"isDefault": true
}
]
}
Refused requests
Unauthenticated caller · HTTP 401
Input
{}
SDK response or error
{
"code": "auth_error",
"status": 401,
"message": "Fixture authentication refused"
}
Service HTTP body
{
"error": "Fixture authentication refused"
}
Verify the result
- Check appId is app_topolo_mail and selected workspace matches the requested resource. Interpret widget data through its returned contractVersion.
Recover
This read requests no delivery or data change. Preserve failures and repeat discovery in the same authorized context; no rollback mutation is needed.
- HTTP 401
auth_error: Authenticate again in the intended environment and context, then repeat identity and action discovery.
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.