Topolo Docs Topolo Platform
Open workspace

Get notification delivery language

Read or configure only the authenticated human recipient’s notification language in the verified workspace. Stored event copy remains bound to its original release.

Read or configure only the authenticated human recipient’s notification language in the verified workspace. Stored event copy remains bound to its original release.

Action app_topolo_success.notification_delivery.get · GET /api/notification-delivery. Intended audience: public.

Catalog flags: readOnly=False, requiresConfirmation=True, destructive=False, agentAccess=confirm. HTTP method and empty permission fields do not override the actual effects or authority below.

Authority and prerequisites

  • Explicit authorization for possible notification delivery, including catalog confirmation on the GET.
  • Declared authorization mode=static, requiredPermission=app_topolo_success.workspace:read; actual source identity/resource checks below remain mandatory.
  • Discover the actual identifier and current intended state within existing authority. Examples grant no access and are not executable probes.

Identifiers

  • Use the current human session and granted workspace resource context. Locale is an exact supported enum, not Accept-Language fallback or another recipient ID.

Input

Pass {}; no body/query recipient override is accepted.

The exact native input/output schemas are retained in the hidden paired layer for this version. Top-level undeclared fields are rejected. Nested open records and semantic prerequisites still need source checks.

Effects and important boundaries

  • API-key callers are refused; caller identity and workspace are resolved by Auth. No recipient identifier is accepted in the input.
  • Dispatch rechecks recipient membership and skips rows with localization_reason, missing data or unknown membership. These source guards do not establish that every historical row has independently verified provenance.
  • Reads the configured locale or null when unconfigured; eligible self pending events can dispatch.
  • Requires a valid authenticated human recipient, active organization and the exact canonical verified workspace. API-key recipients are refused even when their app permission exists. Input accepts no user/org/workspace override.
  • The worker ensures the local workspace identity mirror. This GET is explicitly catalog readOnly=false, requiresConfirmation=true and agentAccess=confirm: it also flushes eligible self-recipient pending notifications. Do not use it as an effect-free probe.
  • Flush rechecks the self recipient’s membership, skips rows with localization_reason or missing data, and leaves unknown membership unresolved. Revoked membership is recorded as revoked; eligible leased rows may be emitted to Notify. Do not infer that every historical row has been provenance-verified.
  • A locale response alone is not a transport count or recipient delivery receipt. Retry payload, original idempotency key and frozen selected event copy remain immutable.

Refusals, failures and recovery

  • 400 invalid_action_input: Correct only the input paths reported by the runtime or CLI validator; retain action id and exact context.
  • 403 action_permission_required: The verified credential lacks the action permission. Stop this action and request the appropriate authorized grant; an identifier or organization ownership does not grant it.
  • 403 organization_required: Verify the authorized organization context; personal scope cannot operate on organization-owned Success data.
  • 400 workspace_required: Discover an authorized app-scoped workspace and pass its resource binding. API keys without a workspace resource are refused.
  • 503 workspaces_unavailable: Preserve the request id and report unavailable platform grants or database binding; do not invent a default workspace.
  • 403 human_recipient_required: Use the same authorized human session; API-key owner projections cannot configure recipient preferences.

Changing language changes future events and selects original frozen copy for waiting events; previously selected retry payloads remain immutable.

Verification

  • Verify locale in the response, customer account state unchanged, and selected event payload/release identity retained on retries. A transport count is not a recipient delivery receipt.
  • Retain actual request/receipt identifiers securely, preserve UNKNOWN effects and reconcile before any retry.

Run a reviewed request

Discover the current action and its resource requirements before running it. Save the approved input as reviewed-input.json; replace synthetic examples with values obtained through the intended authorized workflow. If discovery requires a resource binding, provide its published type and resolved ID separately on both plan and call. Stop if validation fails or the plan is not executable.

topolo actions get app_topolo_success.notification_delivery.get --json
topolo actions validate app_topolo_success.notification_delivery.get --data @reviewed-input.json --json
topolo actions plan app_topolo_success.notification_delivery.get --data @reviewed-input.json --confirm --json
topolo actions call app_topolo_success.notification_delivery.get --data @reviewed-input.json --confirm --json

--confirm must represent approval of the actual request and its effects. The examples do not supply that approval.

Worked examples

All examples are synthetic and unrun. They cannot authorize access, create human consent, prove media/provider success or establish financial/customer state. Placeholder tokens are unusable. No contact, payment, notification, provisioning or business read was executed.

Own preference illustration

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: PASS_STRUCTURAL_ONLY_UNRUN.

Input:

{}

Output illustration or error excerpt:

{
  "locale": null
}

200 returns the preference, with possible delivery effects as described; no notification was sent here.

Refusal or failure

SOURCE-AUTHORED SYNTHETIC, UNRUN. Source-derived error-code excerpt only; messages/envelope can differ by layer or locale. Not a captured response. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{}

Output illustration or error excerpt:

{
  "error": "human_recipient_required"
}

An API key cannot become a human notification recipient.

Invalid input: stop at schema validation

SOURCE-AUTHORED SYNTHETIC, UNRUN. null is a no-response sentinel, not returned JSON null. Output assessment: NOT_APPLICABLE_NO_REQUEST.

Input:

{
  "unexpectedRecipientId": "other_user"
}

Output illustration or error excerpt:

null

Intentionally invalid input; no request was issued and no HTTP response/status is asserted.

Boundary: held or failed notifications remain separate

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: PASS_STRUCTURAL_ONLY_UNRUN.

Input:

{}

Output illustration or error excerpt:

{
  "locale": null
}

The same locale result does not prove held legacy rows were sent, retries changed payload, or any recipient received a message.

Source and verification limits

Reviewed against 161c9eebec330e15d42483b1724a9df3531f0a75 at apps/api/src/worker.ts and the published action schema on 2026-10-20. Examples are synthetic and unrun. Source review and schema validation do not prove current deployed behavior, provider completion or business delivery. Response excerpts are labelled where incomplete.

Change log

  • 2026-10-20: Prepared the action guide with paired agent schemas, permission and effect boundaries, worked examples, verification and recovery instructions. Independently checked the pinned source; publication and runtime verification remain separate.