Outcome
Read versioned channel configuration, capability flags and available recipient/destination choices.
GET /api/forms/{formId}/delivery
Before you start
Use the original authorized organization and a discovered canonical Forms workspace, bound separately as workspace resource context. Resolve formId through authorized Forms reads. Input workspace ids alone grant no access.
GET requires application workspace:read and a bearer workspace read grant. PUT requires application workspace:write plus bearer workspace admin because it controls routing of submitted personal data. API keys retain the exact Auth-verified resource binding and actual application permission; no unimplemented local API-key admin check is asserted.
Public guides contain fictional source-derived UNRUN responses. Real confirmation copy, recipient directories, destinations, project mappings and operational output remain within the authorized audience. No actual private read, configuration, send, CRM/Consent/Nexus/model/key operation was executed.
Request and behavior
Action: app_topolo_forms.delivery_settings.get. Validate the exact published input and bind workspace separately. Read only; no confirmation or metered AI request is needed.
GET returns HTTP200 {delivery,destinations,nexusUrl,recipients,capabilities}. delivery contains the full settings document, formId,version,configured,updatedAt,updatedByUserId. It additionally asks the service-owned Auth organization directory and Nexus destination resolver for current choices; this is not merely a local settings row read.
recipients is null when the directory is unavailable, or an array of {id,name,email}; an empty array means a successful response with no qualifying entries. The selected directory fetch asks for limit500, filters out entries with an explicit non-active status and invalid ids, trims names/email and returns null on unavailable/unexpected carrier. No complete paged organization directory is promised.
destinations is null when unavailable or an array returned by the configured resolver. nexusUrl is configured NEXUS_GATEWAY_URL or null; it is not an executable action grant. Reading these choices does not change settings, enqueue channels, send notifications or prove destination reachability.
Stored documents are overlaid on defaults for older missing sections/keys. This read is not a fresh merge/field-reference validation against the current form, and can expose mappings that later become invalid. Confirmation ownership modes come from separate stored columns. No cross-service snapshot joins form/settings/directory/destinations.
Stored settings and readiness
The selected source first reads the form under the original organization/workspace. Missing or out-of-scope form returns404 {error:not_found}. Stored settings JSON is protected under the environment-aware policy and unprotected for an authorized reader. Failure is not permission to downgrade protection or substitute another tenant.
Five channel sections are confirmation,notification,crm,consent,outbound. Missing stored row returns complete defaults, version0,configuredfalse and null update metadata without inserting a row. A stored row returns configuredtrue, numeric version and update metadata. configured means a row exists, not that any channel is enabled or working.
Capability flags are configuration-presence checks, not live readiness. Confirmation/notification need Notify URL plus service credential; CRM/outbound use Nexus URL plus service credential; Consent checks its URL. Flags do not verify recipient permission, service reachability, external provider setup, project validity or delivery outcomes.
Real settings and directory responses can contain user names/email, copy, destination ids and consent project/mapping data. They are authenticated application data; this public guide makes none of that content public.
Worked examples
No stored settings, external directories unavailable
Complete source-derived synthetic UNRUN HTTP200. Form exists; no settings row; Notify/Nexus/Consent and directory prerequisites absent. null directories are not empty successful directories.
Input:
{
"formId": "forms_docs_fixture"
}
Response:
{
"delivery": {
"formId": "forms_docs_fixture",
"settings": {
"confirmation": {
"enabled": false,
"emailFieldId": null,
"subjectMode": "default",
"bodyMode": "default",
"subject": "",
"body": "",
"replyTo": null
},
"notification": {
"enabled": false,
"recipientUserIds": [],
"channels": [
"in_app",
"email"
]
},
"crm": {
"enabled": false,
"leadSource": "Topolo Forms",
"tags": null,
"emailFieldId": null,
"fullNameFieldId": null,
"firstNameFieldId": null,
"lastNameFieldId": null,
"companyFieldId": null,
"phoneFieldId": null,
"jobTitleFieldId": null,
"utmSourceFieldId": null,
"utmMediumFieldId": null,
"utmCampaignFieldId": null,
"utmTermFieldId": null,
"utmContentFieldId": null
},
"consent": {
"enabled": false,
"projectKey": null,
"identityFieldId": null,
"region": null,
"mappings": []
},
"outbound": {
"enabled": false,
"destinationIds": [],
"fieldIds": []
}
},
"version": 0,
"configured": false,
"updatedAt": null,
"updatedByUserId": null
},
"destinations": null,
"nexusUrl": null,
"recipients": null,
"capabilities": {
"confirmation": {
"available": false,
"reason": "notify_not_configured"
},
"notification": {
"available": false,
"reason": "notify_not_configured"
},
"outbound": {
"available": false,
"reason": "nexus_not_configured"
},
"crm": {
"available": false,
"reason": "crm_not_configured"
},
"consent": {
"available": false,
"reason": "consent_not_configured"
}
}
}
Compare only with the actual authorized target and documented state. Fictional examples authorize no live configuration, delivery or private-directory operation.
Stored configuration without a working delivery capability
Complete source-derived synthetic UNRUN HTTP200. Stored version1 enables confirmation mapped to current email field, but integration configuration is absent. configuredtrue and enabledtrue do not imply any send occurred or can succeed.
Input:
{
"formId": "forms_docs_fixture"
}
Response:
{
"delivery": {
"formId": "forms_docs_fixture",
"settings": {
"confirmation": {
"enabled": true,
"emailFieldId": "email",
"subjectMode": "default",
"bodyMode": "default",
"subject": "",
"body": "",
"replyTo": null
},
"notification": {
"enabled": false,
"recipientUserIds": [],
"channels": [
"in_app",
"email"
]
},
"crm": {
"enabled": false,
"leadSource": "Topolo Forms",
"tags": null,
"emailFieldId": null,
"fullNameFieldId": null,
"firstNameFieldId": null,
"lastNameFieldId": null,
"companyFieldId": null,
"phoneFieldId": null,
"jobTitleFieldId": null,
"utmSourceFieldId": null,
"utmMediumFieldId": null,
"utmCampaignFieldId": null,
"utmTermFieldId": null,
"utmContentFieldId": null
},
"consent": {
"enabled": false,
"projectKey": null,
"identityFieldId": null,
"region": null,
"mappings": []
},
"outbound": {
"enabled": false,
"destinationIds": [],
"fieldIds": []
}
},
"version": 1,
"configured": true,
"updatedAt": "2026-10-21T00:00:00.000Z",
"updatedByUserId": "usr_docs_fixture"
},
"destinations": null,
"nexusUrl": null,
"recipients": null,
"capabilities": {
"confirmation": {
"available": false,
"reason": "notify_not_configured"
},
"notification": {
"available": false,
"reason": "notify_not_configured"
},
"outbound": {
"available": false,
"reason": "nexus_not_configured"
},
"crm": {
"available": false,
"reason": "crm_not_configured"
},
"consent": {
"available": false,
"reason": "consent_not_configured"
}
}
}
Compare only with the actual authorized target and documented state. Fictional examples authorize no live configuration, delivery or private-directory operation.
Missing form
Complete source-derived synthetic UNRUN HTTP404. Authorized scoped form lookup returns no row, before directory reads.
Input:
{
"formId": "forms_absent_docs_fixture"
}
Response:
{
"error": "not_found"
}
Compare only with the actual authorized target and documented state. Fictional examples authorize no live configuration, delivery or private-directory operation.
Verify and recover
-
Keep actual formId,original organization/workspace and the exact settings version. For updates, compare full returned settings and updatedByUserId with the approved change, then authorized GET version/content read-back; do not replay a lost successful save.
-
Do not interpret configured,enabled or capabilitypresence as actual delivery/readiness. Directory null/unavailable, staleness, revoked recipients and external outcomes require their own supported verification and authority.
-
Preserve sanitized request/status evidence on auth/database/protection/integration failures. No test send, export, retry, provider call or key change is authorized as a documentation check.
Read only. Preserve actual failures; unavailable choices are not a reason to create destinations, change grants/keys or send messages.
Errors
404 / not_found: Reconcile the discovered form id and original authorized workspace.
403 / forbidden: Keep the denial and original identity; seek legitimate grant from its owner.
Shared auth/protection errors retain their actual service carrier; local schema rejection is not a captured handler response. The update constraints and concrete conflicts/directories errors are described above.
Related actions
Change log
- 2026-10-21: Added exact full settings model, configuration/readiness distinction, directory and routing boundaries, versioned update behavior, complete synthetic success/refusal responses and scoped recovery. Examples remain unrun.