Topolo Docs Topolo Platform
Open workspace

Read contact receipt

Read a stored contact receipt using its random reference. No message, identity or email delivery state is returned.

Read a stored contact receipt using its random reference. No message, identity or email delivery state is returned.

Action app_topolo_one.marketing.contact.get · GET /api/contact/receipt. Intended audience: public.

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

Authority and prerequisites

  • Declared authorization mode=public, requiredPermission=empty; 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 exact contactId returned by the corresponding contact submission; example IDs identify no live enquiry.

Input

  • contactId: type="string"; pattern="^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$". Required.

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

  • Reads only receipt metadata for the exact random reference. It returns no personal information, message or delivery state.
  • Public transport, scoped by possession of the random UUID v4 contact reference. Return data is only the reference, receivedAt and received status; it exposes no message, name/email or delivery state.
  • A missing/expired or not-yet-visible reference returns CONTACT_NOT_FOUND. Dependency failure is CONTACT_UNAVAILABLE, not evidence of absence.
  • Protect the receipt reference and use only the one from your authorized submission. Do not enumerate references or submit again merely to test storage.

Refusals, failures and recovery

  • 400 VALIDATION_ERROR: Use the UUID returned by the successful submission.
  • 404 CONTACT_NOT_FOUND: The reference is not visible or has expired. After a recent successful write, retry the read before submitting again.
  • 503 CONTACT_UNAVAILABLE: Retry the read after contact storage is restored.

This read changes no contact, subscription or charge.

Verification

  • Confirm receipt.contactId matches the submitted reference and status is received. KV propagation can delay visibility after creation.
  • 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_one.marketing.contact.get --json
topolo actions validate app_topolo_one.marketing.contact.get --data @reviewed-input.json --json
topolo actions plan app_topolo_one.marketing.contact.get --data @reviewed-input.json --json
topolo actions call app_topolo_one.marketing.contact.get --data @reviewed-input.json --json

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.

Read receipt illustration

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

Input:

{
  "contactId": "00000000-0000-4000-8000-000000000001"
}

Output illustration or error excerpt:

{
  "success": true,
  "receipt": {
    "contactId": "00000000-0000-4000-8000-000000000001",
    "receivedAt": "2026-10-20T00:00:00.000Z",
    "status": "received"
  }
}

200 receipt only; no email delivery conclusion.

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:

{
  "contactId": "00000000-0000-4000-8000-000000000001"
}

Output illustration or error excerpt:

{
  "error": "CONTACT_NOT_FOUND"
}

The referenced receipt is not visible or expired; do not infer that a prior write definitely failed.

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:

{}

Output illustration or error excerpt:

null

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

Boundary: storage unavailable

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

Input:

{
  "contactId": "00000000-0000-4000-8000-000000000001"
}

Output illustration or error excerpt:

{
  "error": "Contact receipt unavailable.",
  "code": "CONTACT_UNAVAILABLE"
}

503, distinct from a missing receipt.

Source and verification limits

Reviewed against cb18601dad6735f8140a4c81e9650d9fc3599f9a at apps/marketing/worker/engagement-routes.js 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.