Transcribe Mail audio

Transcribe reviewed audio for composing a Mail draft.

Outcome

Transcribe reviewed audio for composing a Mail draft.

Before you start

Verify the intended environment, credential and authorized organization context before discovery.
Discover Mail, the exact action and its agent:use 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 live inline-base64 upload descriptor, inspect its size/MIME restrictions and review the actual audio before confirming a metered transcription.

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.transcriptions.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.transcriptions.create --data @payload.json --json
topolo actions plan app_topolo_mail.transcriptions.create --resource-type workspace --resource-id <discovered-workspace-id> --data @payload.json --confirm --json
topolo actions call app_topolo_mail.transcriptions.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.

For file upload convenience, save the discovered mailboxId and optional transcription hints as scope.json. Review the file and the same derived payload before confirmation.

topolo actions upload app_topolo_mail.transcriptions.create --file <reviewed-audio-file> --content-type audio/webm --resource-type workspace --resource-id <discovered-workspace-id> --data @scope.json --confirm --json

For MCP, SDK or CLI upload, follow the exact current action/upload descriptor, inspect the prepared request and bind the discovered mailboxId and workspace separately. The exact source closure for this candidate verifies the Mail web dictation path only; it does not establish that browser, SDK, CLI and MCP encoders emit identical bytes or fields. The SDK upload path is exercised against a synthetic catalog and local handler; deployed catalog and provider proof remain separate.

Input fields

Field	Required	Meaning
`mailboxId`	Yes	Mailbox ID from mailboxes.collection.list in the selected workspace; it is distinct from the workspace resource ID.
`audioBase64`	Yes	Canonical base64-encoded reviewed audio bytes, non-empty and at most 8 MiB decoded. The Mail browser dictation component builds this field from recorded bytes; other client encoders are not verified by this source closure.
`mimeType`	Yes	Exact base audio media type accepted by the published upload descriptor. The browser source strips recorder parameters and lowercases the media type before deriving this field. Other client encoder behavior is not verified here; an accepted media type does not prove intelligible speech.
`fileName`	Yes	Non-empty reviewed audio filename supplied by the upload helper; it is metadata, not a local filesystem path for the server.
`durationMs`	No	Optional positive integer recording-duration estimate in milliseconds.
`language`	No	Optional language hint for transcription; review the actual returned speech.
`initialPrompt`	No	Optional transcription context; the handler trims it and retains its last 400 characters.

Effects

Sends audio to metered Nexus transcription. No draft or email is created automatically.

Interpret the response

data.text/model/requestId contain the transcription result. The canonical JSON inline-base64 upload carries non-empty reviewed audio at most 8 MiB decoded plus fileName and an accepted mimeType. Optional durationMs is a positive integer estimate, language is a hint, and initialPrompt is trimmed to its last 400 characters. Browser dictation and SDK/CLI/MCP upload helpers use this same contract. Retained synthetic audio and controlled Nexus responses prove transport and handler behavior, not speech quality or a deployed provider outcome.

Worked requests and responses

Successful fixture request · HTTP 200

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "c3ludGhldGljLWF1ZGlvLWZpeHR1cmU=",
  "mimeType": "audio/webm",
  "fileName": "fixture.webm"
}

SDK response or error

{
  "success": true,
  "data": {
    "text": "Synthetic transcription.",
    "model": "fixture-transcription",
    "requestId": "fixture-nexus-request"
  }
}

Refused requests

Unauthenticated caller · HTTP 401

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "c3ludGhldGljLWF1ZGlvLWZpeHR1cmU=",
  "mimeType": "audio/webm",
  "fileName": "fixture.webm"
}

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

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "c3ludGhldGljLWF1ZGlvLWZpeHR1cmU=",
  "mimeType": "audio/webm",
  "fileName": "fixture.webm"
}

SDK response or error

{
  "code": "permission_denied",
  "status": 403,
  "message": "TopoloMail permission denied"
}

Service HTTP body

{
  "success": false,
  "error": {
    "message": "TopoloMail permission denied"
  }
}

Other organization · HTTP 403

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "c3ludGhldGljLWF1ZGlvLWZpeHR1cmU=",
  "mimeType": "audio/webm",
  "fileName": "fixture.webm"
}

SDK response or error

{
  "code": "permission_denied",
  "status": 403,
  "message": "Mailbox does not belong to your organization"
}

Service HTTP body

{
  "success": false,
  "error": {
    "message": "Mailbox does not belong to your organization"
  }
}

Other verified workspace · HTTP 404

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "c3ludGhldGljLWF1ZGlvLWZpeHR1cmU=",
  "mimeType": "audio/webm",
  "fileName": "fixture.webm"
}

SDK response or error

{
  "code": "http_error",
  "status": 404,
  "message": "Mailbox not found"
}

Service HTTP body

{
  "success": false,
  "error": {
    "message": "Mailbox not found"
  }
}

Refused semantic request · HTTP 400

Input

{
  "mailboxId": "mbx_mail_fixture"
}

SDK response or error

{
  "code": "invalid_upload_content",
  "status": 400,
  "message": "Upload content must be canonical base64."
}

Service HTTP body

{
  "success": false,
  "error": {
    "code": "invalid_upload_content",
    "message": "Upload content must be canonical base64."
  }
}

Refused semantic request · HTTP 400

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "bad-base64",
  "mimeType": "audio/webm",
  "fileName": "fixture.webm"
}

SDK response or error

{
  "code": "invalid_upload_content",
  "status": 400,
  "message": "Upload content must be canonical base64."
}

Service HTTP body

{
  "success": false,
  "error": {
    "code": "invalid_upload_content",
    "message": "Upload content must be canonical base64."
  }
}

Refused semantic request · HTTP 400

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "",
  "mimeType": "audio/webm",
  "fileName": "fixture.webm"
}

SDK response or error

{
  "code": "invalid_upload_content",
  "status": 400,
  "message": "Upload content must be canonical base64."
}

Service HTTP body

{
  "success": false,
  "error": {
    "code": "invalid_upload_content",
    "message": "Upload content must be canonical base64."
  }
}

Refused semantic request · HTTP 400

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "c3ludGhldGljLWF1ZGlvLWZpeHR1cmU=",
  "mimeType": "text/plain",
  "fileName": "fixture.webm"
}

SDK response or error

{
  "code": "unsupported_upload_content_type",
  "status": 400,
  "message": "Content type \"text/plain\" is not accepted by this action."
}

Service HTTP body

{
  "success": false,
  "error": {
    "code": "unsupported_upload_content_type",
    "message": "Content type \"text/plain\" is not accepted by this action."
  }
}

Refused semantic request · HTTP 400

Input

{
  "mailboxId": "mbx_mail_fixture",
  "audioBase64": "c3ludGhldGljLWF1ZGlvLWZpeHR1cmU=",
  "mimeType": "audio/webm",
  "fileName": ""
}

SDK response or error

{
  "code": "invalid_upload_file_name",
  "status": 400,
  "message": "Upload fileName must not be empty."
}

Service HTTP body

{
  "success": false,
  "error": {
    "code": "invalid_upload_file_name",
    "message": "Upload fileName must not be empty."
  }
}

Verify the result

Review returned text against the actual audio and intended language before a separately approved draft creation. Preserve requestId for diagnostics.

Recover

A transcript sends nothing. Inspect an uncertain paid request before retrying. Discover the live upload descriptor, correct only its encoding, filename, MIME or size refusal, and review returned text before draft creation.

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.
HTTP 404 http_error: Rediscover the exact mailbox and child IDs in the same authorized workspace; do not guess another ID.
HTTP 400 invalid_upload_content: Inspect this captured refusal: Upload content must be canonical base64.. Correct only the reviewed request or prerequisite, revalidate it, and plan again. Do not repeat an uncertain send, paid generation or deletion.
HTTP 400 unsupported_upload_content_type: Inspect this captured refusal: Content type "text/plain" is not accepted by this action.. Correct only the reviewed request or prerequisite, revalidate it, and plan again. Do not repeat an uncertain send, paid generation or deletion.
HTTP 400 invalid_upload_file_name: Inspect this captured refusal: Upload fileName must not be empty.. Correct only the reviewed request or prerequisite, revalidate it, and plan again. Do not repeat an uncertain send, paid generation or deletion.
HTTP 413 upload_too_large: Reduce the reviewed audio to at most 8 MiB decoded, then derive and validate the unchanged upload fields again before confirmation. The actual handler boundary tests cover acceptance at the limit and refusal above it; the guide omits the large base64 literal.

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.

Create Mail draft

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.

Transcribe Mail audio

Outcome

Before you start

Discover the target

Request

Input fields

Effects

Interpret the response

Worked requests and responses

Successful fixture request · HTTP 200

Refused requests

Unauthenticated caller · HTTP 401

Permission denied · HTTP 403

Other organization · HTTP 403

Other verified workspace · HTTP 404

Refused semantic request · HTTP 400

Refused semantic request · HTTP 400

Refused semantic request · HTTP 400

Refused semantic request · HTTP 400

Refused semantic request · HTTP 400

Verify the result

Recover

Related actions

Evidence and limits