Get event delivery status

Read the organization’s locally stored subscription view for the seven Nexus email event types. connected is true when all seven local rows are active. This does not contact Notify or prove remote subscription existence, signature agreement or actual event delivery. No signing secret is returned.

Before you start

Use production unless development or staging is explicitly scoped, and keep the same authorized organization throughout. Reading this guide does not execute an action.
Discover the current published action and validate/plan exact input before any later execution. Honor the current published confirmation and runtime authorization requirements.
Required published permission: app_topolo_engage.workspace:read.
Select the verified organization separately from action input and retain workspace:read authorization. The status handler itself requires no workspace selection, organization-admin role, Notify administrator bearer, configured signing key or Notify ports; it reads only the local view.
The Worker authenticates through rt.verifyAuth/rt.authError before routing; authentication refusal is an outer-boundary result, not the mutation-only user_credential_required guard. Local storage failures propagate to shared error middleware; preserve the actual returned status and request identifier without inventing a stable storage error code or treating failure as disconnected.

Effects and limits

Reads locally stored Engage event-subscription state for the current authorized organization. Does not call Notify to verify live subscriptions, signatures or delivery.

Request

GET /api/events/delivery

Inputs below are source-derived synthetic examples, not approval to execute. Discover resource context separately.

Input fields

Field	Required	Type and constraints
No body fields	—	Use the empty object `{}`; keep organization selection outside the body.

Worked examples

Every request/response below is synthetic and unrun, authored from reviewed source and retained published schemas. It is not a captured local or production response. Fixture identities and timestamps authorize nothing.

Read stored not_connected state

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{}

Response illustration:

{
  "delivery": {
    "connected": false,
    "status": "not_connected",
    "eventTypes": [
      {
        "eventType": "nexus.email.delivered",
        "status": "not_connected",
        "notifySubscriptionId": null,
        "createdBy": null,
        "createdAt": null,
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.bounced.hard",
        "status": "not_connected",
        "notifySubscriptionId": null,
        "createdBy": null,
        "createdAt": null,
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.bounced.soft",
        "status": "not_connected",
        "notifySubscriptionId": null,
        "createdBy": null,
        "createdAt": null,
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.complained",
        "status": "not_connected",
        "notifySubscriptionId": null,
        "createdBy": null,
        "createdAt": null,
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.replied",
        "status": "not_connected",
        "notifySubscriptionId": null,
        "createdBy": null,
        "createdAt": null,
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.auto_reply",
        "status": "not_connected",
        "notifySubscriptionId": null,
        "createdBy": null,
        "createdAt": null,
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.unsubscribed",
        "status": "not_connected",
        "notifySubscriptionId": null,
        "createdBy": null,
        "createdAt": null,
        "rotatedAt": null
      }
    ]
  }
}

Interpret only stored Engage rows. Local active does not prove remote webhook existence, signature agreement or actual event delivery.

Read stored active state

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{}

Response illustration:

{
  "delivery": {
    "connected": true,
    "status": "active",
    "eventTypes": [
      {
        "eventType": "nexus.email.delivered",
        "status": "active",
        "notifySubscriptionId": "whsub_example_1",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.bounced.hard",
        "status": "active",
        "notifySubscriptionId": "whsub_example_2",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.bounced.soft",
        "status": "active",
        "notifySubscriptionId": "whsub_example_3",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.complained",
        "status": "active",
        "notifySubscriptionId": "whsub_example_4",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.replied",
        "status": "active",
        "notifySubscriptionId": "whsub_example_5",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.auto_reply",
        "status": "active",
        "notifySubscriptionId": "whsub_example_6",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.unsubscribed",
        "status": "active",
        "notifySubscriptionId": "whsub_example_7",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      }
    ]
  }
}

Interpret only stored Engage rows. Local active does not prove remote webhook existence, signature agreement or actual event delivery.

Read stored partial state

SOURCE-DERIVED SYNTHETIC UNRUN example. This is authored illustration, not a captured response, live authorization, provider result or test pass.

Request:

{}

Response illustration:

{
  "delivery": {
    "connected": false,
    "status": "partial",
    "eventTypes": [
      {
        "eventType": "nexus.email.delivered",
        "status": "revoked",
        "notifySubscriptionId": "whsub_example_1",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.bounced.hard",
        "status": "active",
        "notifySubscriptionId": "whsub_example_2",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.bounced.soft",
        "status": "active",
        "notifySubscriptionId": "whsub_example_3",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.complained",
        "status": "active",
        "notifySubscriptionId": "whsub_example_4",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.replied",
        "status": "active",
        "notifySubscriptionId": "whsub_example_5",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.auto_reply",
        "status": "active",
        "notifySubscriptionId": "whsub_example_6",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      },
      {
        "eventType": "nexus.email.unsubscribed",
        "status": "active",
        "notifySubscriptionId": "whsub_example_7",
        "createdBy": "user_original_example",
        "createdAt": "2026-10-20T00:00:00.000Z",
        "rotatedAt": null
      }
    ]
  }
}

Interpret only stored Engage rows. Local active does not prove remote webhook existence, signature agreement or actual event delivery.

Verify the result

Call events.delivery.status and check delivery.status and each eventTypes[].status.

Errors and recovery

403 organization_required: Select the exact authorized organization through supported identity/resource discovery; do not fabricate an organization or widen credentials.
403 permission_denied: Honor the workspace:read permission check against the verified organization; stop for owner review rather than changing credential type or calling a mutation.
422 invalid_action_input: Use the published empty-object input and separate organization resource selection. Correct declared input only; do not connect or retry a mutation to diagnose this read.

The Worker authenticates through rt.verifyAuth/rt.authError before routing; authentication refusal is an outer-boundary result, not the mutation-only user_credential_required guard. Local storage failures propagate to shared error middleware; preserve the actual returned status and request identifier without inventing a stable storage error code or treating failure as disconnected.

No mutation to reverse. Preserve unavailable/denied state; do not convert a read failure into disconnected state or infer provider health from local rows. Do not switch to a Notify administrator or call connect/rotate/disconnect as read recovery.

Evidence and change log

2026-10-20: Prepared this paired guide from source 767d2d83713809e984559eee562a2c9f7ffcfa4d and the retained production contract snapshot. Independent source/content/audience review is complete. Examples remain explicitly synthetic and unrun; no original response capture or business execution is claimed.
Source-reviewed guidance preserves partial/uncertain subscription effects and local-only status; current catalogue recovery/scope/actor wording is under owner review.

Published contract wording under review

The retained catalogue description/recovery text includes stronger no-change or automatic-undo wording than this source supports. The published schema annotations are retained exactly for comparison; they are not a guarantee that compensation or provider delivery succeeds. Follow the source-qualified limits above.

The retained catalogue shared error list includes user_credential_required, notify_admin_required, event_delivery_not_connected, notify_refused, notify_unavailable and event_delivery_not_configured. Those mutation-only ready/Notify outcomes are not emitted by this local status handler and are retained only as a catalogue discrepancy, not operative status prerequisites or recovery instructions. There is no blanket Retry; nothing changed rule for this read.

Exact published-field qualifications

/outputSchema/properties/delivery/properties/eventTypes/items/properties/createdBy/description: Source-qualified limit: createdBy is the stored connection creator for that row, not the rotation actor. A later rotatedAt does not identify who rotated it.
/outputSchema/properties/delivery/properties/connected/description: Source-qualified limit: connected classifies whether all seven current local rows are active. It does not prove remote subscription existence, health, signature agreement or event delivery.
/outputSchema/properties/delivery/properties/status/description: Source-qualified limit: status classifies the seven current local rows only. not_connected is not proof that the organization has never connected in the past; legacy rows are excluded from this view.

The original published schema annotations remain evidence under review. Validation types/enums are unchanged; these guide qualifications do not assert a corrected catalogue publication or remote state.