Topolo Docs Topolo Platform
Open workspace

Archive prospect contact

Archive a retained contact while keeping its address reservation and historical record.

Outcome

Archive a retained contact while keeping its address reservation and historical record.

Before you start

  • Verify the environment, credential, authorized organization and the published action permission workspace:write.
  • Discover an accessible Engage workspace and bind resourceType=workspace and its resourceId separately from action input. Fixture identifiers grant no access.
  • Approve the exact mutation and its effects before CLI --confirm or MCP confirm:true. This documentation does not authorize outreach.

Discover the target

  • Use contacts.list or contacts.resolve to discover the contact in the selected workspace. Read contacts.get and retain the current profile, custom fields and archivedAt before planning.
topolo whoami --json
topolo actions get app_topolo_engage.contacts.archive --json
topolo workspaces list topolo-engage --json

Input fields

FieldRequiredMeaning and constraints
idYesRequired identifier discovered or retained in the same authorized workspace, trimmed non-empty string up to 128 characters.

Validate, plan and execute

Set ENGAGE_WORKSPACE_ID to the identifier of your selected workspace. Prepare payload.json from the current input schema and discovered identifiers. Use the same payload for validation, planning and execution.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions validate app_topolo_engage.contacts.archive --data @payload.json --json
topolo actions plan app_topolo_engage.contacts.archive --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --confirm --json

Review the plan and obtain approval for the exact effects before executing the unchanged request.

: "${ENGAGE_WORKSPACE_ID:?Set ENGAGE_WORKSPACE_ID to your selected workspace identifier}"
topolo actions call app_topolo_engage.contacts.archive --resource-type workspace --resource-id "$ENGAGE_WORKSPACE_ID" --data @payload.json --confirm --json

For MCP, use topolo_get_action, topolo_validate_action, topolo_plan_action and topolo_call_action. Pass the selected resource context separately; confirm:true is required for mutations.

Worked requests and responses

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_1"
}

Actual local response

{
  "contact": {
    "id": "contact_1",
    "email": "ada@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "company": "Analytical",
    "title": "CTO",
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {
      "LinkedIn": "https://www.linkedin.com/in/ada",
      "Phone": "+44 20 0000"
    },
    "createdAt": "2026-10-06T08:30:00.000Z",
    "updatedAt": "2026-10-06T08:30:00.000Z",
    "archivedAt": "2026-10-06T08:30:00.000Z"
  }
}

Source test: tasks.* actions > shows no contact for an archived contact. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_1"
}

Actual local response

{
  "contact": {
    "id": "contact_1",
    "email": "ada@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "company": "Analytical",
    "title": null,
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {},
    "createdAt": "2026-10-06T08:30:00.000Z",
    "updatedAt": "2026-10-06T08:30:00.000Z",
    "archivedAt": "2026-10-06T08:30:00.000Z"
  }
}

Source test: runDueSends > ending enrollments the runner cannot continue > stops for an archived contact, a deleted seat, or a missing step. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_1"
}

Actual local response

{
  "contact": {
    "id": "contact_1",
    "email": "ada@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": "Ada",
    "lastName": null,
    "company": null,
    "title": "Countess",
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {
      "tier": "a",
      "region": "uk"
    },
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: audience routes > contacts > creates, reads, searches, edits and archives a manual contact. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_1"
}

Actual local response

{
  "contact": {
    "id": "contact_1",
    "email": "ada@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": null,
    "lastName": null,
    "company": null,
    "title": null,
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {},
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: audience routes > contacts.resolve > reports an archived contact and stays inside the workspace. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_2"
}

Actual local response

{
  "contact": {
    "id": "contact_2",
    "email": "grace@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": null,
    "lastName": null,
    "company": null,
    "title": null,
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {},
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: audience routes > lists > adds and removes members, counting only active contacts. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_3"
}

Actual local response

{
  "contact": {
    "id": "contact_3",
    "email": "old@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": null,
    "lastName": null,
    "company": null,
    "title": null,
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {},
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: audience routes > imports > updates changed contacts, matches unchanged ones and adds both to the list under a new key. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_3"
}

Actual local response

{
  "contact": {
    "id": "contact_3",
    "email": "alan@turing.org",
    "domain": "turing.org",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": null,
    "lastName": null,
    "company": null,
    "title": null,
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {},
    "createdAt": "2026-10-01T12:00:00.000Z",
    "updatedAt": "2026-10-01T12:00:00.000Z",
    "archivedAt": "2026-10-01T12:00:00.000Z"
  }
}

Source test: contactability routes > eligibility > checks recipients: eligible, blocked, undeliverable and without a contact point. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_3"
}

Actual local response

{
  "contact": {
    "id": "contact_3",
    "email": "gone@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "company": "Analytical",
    "title": null,
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {},
    "createdAt": "2026-10-06T08:30:00.000Z",
    "updatedAt": "2026-10-06T08:30:00.000Z",
    "archivedAt": "2026-10-06T08:30:00.000Z"
  }
}

Source test: enrollment routes > enrolls a list and reports every contact it skipped and why. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 200

Action input

{
  "id": "contact_4"
}

Actual local response

{
  "contact": {
    "id": "contact_4",
    "email": "gone@acme.io",
    "domain": "acme.io",
    "addressType": "person",
    "verificationStatus": "unknown",
    "firstName": null,
    "lastName": null,
    "company": null,
    "title": null,
    "website": null,
    "country": null,
    "timezone": null,
    "source": "manual",
    "custom": {},
    "createdAt": "2026-10-01T00:00:00.000Z",
    "updatedAt": "2026-10-01T00:00:00.000Z",
    "archivedAt": "2026-10-01T00:00:00.000Z"
  }
}

Source test: contacts.qualify > isolates per-contact failures: unusable replies and upstream errors fail only that contact; unknown and archived ones are skipped. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Effects and response meaning

  • Sets archivedAt and updatedAt; contact search and active list counts omit it. The stored contact, address reservation and membership rows remain. This is archiving, not privacy erasure.
  • Returns archived contact. Repeating archive returns state_conflict. No contact-unarchive action is presented. Recreating the same email returns duplicate_contact; archiving is not a documented recall of previously sent messages.

Verify the result

  • Read contacts.get and confirm archivedAt is set; contacts.resolve should still resolve the reserved address with archived:true. Do not use absence from one search page alone as proof.

Recover

After a lost response, read contacts.get first. If archivedAt is set, do not repeat archive. There is no documented unarchive action, and creating the same email is blocked by its retained address reservation. Escalate an unintended archive rather than improvising restoration.

Refused responses

Captured contacts.archive · HTTP 409

Action input

{
  "id": "contact_1"
}

Actual local response

{
  "error": {
    "code": "state_conflict",
    "message": "This contact is already archived."
  }
}

Source test: audience routes > contacts > creates, reads, searches, edits and archives a manual contact. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Captured contacts.archive · HTTP 404

Action input

{
  "id": "contact_1"
}

Actual local response

{
  "error": {
    "code": "not_found",
    "message": "Contact was not found in this workspace."
  }
}

Source test: audience routes > contacts > returns 404 for a contact in another workspace or organization. Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

Error recovery

  • HTTP 403 permission_denied: Stop and inspect the permission required by this action in the current credential. Do not broaden permissions or switch organization automatically.
  • HTTP 422 invalid_action_input: Correct the request against the current input schema and validate it again before planning.
  • HTTP 409 state_conflict: Read the exact retained contact or list and inspect archivedAt. Archived records cannot be edited or have list memberships changed; repeated archive is refused. Do not invent an unarchive operation.
  • HTTP 404 not_found: Rediscover the identifier in the same authorized workspace. An identifier from another workspace is not a valid substitute; retain archived identifiers for direct reads.

Evidence and limits

  • contracts/audience.mjs

  • contracts/audience-filter.mjs

  • apps/api/src/audience/audience-routes.ts

  • apps/api/src/audience/contacts-handlers.ts

  • apps/api/src/audience/contact-search.ts

  • apps/api/src/audience/contacts-repository.ts

  • apps/api/src/audience/lists-handlers.ts

  • apps/api/src/audience/lists-repository.ts

  • apps/api/src/audience/filter-source.ts

  • apps/api/test/audience-routes.test.ts

  • apps/api/test/segments-routes.test.ts

  • Actual route handlers with SQLite repositories; synthetic identity/workspace grants and provider ports.

  • Widget/bootstrap use actual app handler but mocked worker runtime and app identity.

  • No gateway execution, live permissions, external delivery or deployed proof.

The examples are local route captures with synthetic context and simulated providers. They do not prove live authorization, CLI/MCP gateway execution, production state or delivery.