Skip to main content

​
Troubleshooting: archival channel enablement

Two archival gates can stall a send or an export mid-flow. Both are tenant-owned controls, and both refuse rather than half-commit — you read the posted control posture once, then fix it once.
  • Contact-archive freeze — a contact set to the archived lifecycle stage stops receiving dispatch and routes it out of the active funnel.
  • Archival-policy channel gate — POST /compliance/archival/export returns 409 ARCHIVAL_CHANNEL_NOT_ENABLED when the export names a channel the policy does not enable (or when archival was never enabled). A legal-hold or archive flow that fans out over channels stops at the first blocked one.
Find the gate that fired below, then jump to its section.
Archival is a tenant-owned control: your org records the policy and chooses the channels the immutable copies cover. The refuse below is the platform honoring your recorded posture, not a platform fault — resolve it from your side as below.

​
Contact-archive freeze

Archiving a contact is a freeze, not a delete. The row moves to the archived lifecycle stage, drops out of the active funnel, and stops receiving new dispatch — a campaign, a flow enrollment, or a one-off send that targets it re-routes around it or refuses. This is what you want when you set a contact aside under retention or legal-hold scope: the record stays, but further sends cannot accidentally reach it. It becomes a block when a later flow picks the archived row as a target — a stalling send that never confirms. The freeze holds until the target is explicitly unarchived: a plain PATCH /contacts/{id} that carries lifecycle_stage for an archived row refuses with 409 CONTACT_ARCHIVED unless you pass the companion unarchive: true flag in the same call. That guard stops an unrelated edit (a name change, for example) from silently reactivating a contact you deliberately froze. Fix — reactivate deliberately, or route around the frozen target:
  1. Confirm the target. Read the contact and check lifecycle_stage is archived.
  2. Either nominate another, active contact for the send, or unarchive: PATCH /contacts/{id} with lifecycle_stage: "active" (or whichever stage you want back) and unarchive: true in the same body.
  3. Re-run the send or flow. The gate reads the stage synchronously, so the same dispatch goes through as soon as the row is active again.
Bulk pipelines (import wizards, bulk edits) are the common way a frozen contact gets re-staged — the same unarchive: true companion flag is what those surfaces pass, and the same guard applies. If the send is a legal-hold or archive flow, check the channel gate below before you re-file.

​
Archival channel not enabled

On POST /compliance/archival/export, 409 ARCHIVAL_CHANNEL_NOT_ENABLED means the export named a channel — sms, mms, or voice (call recordings) — that the archival policy does not include, or that archival was never enabled on the org at all. The export refuses rather than half-collecting a channel the policy excludes, because an immutable bundle that silently skips an expected channel is worse than no bundle. A legal-hold or archive workflow that fans out a bundle across channels stalls at the first blocked channel: the request fails as a whole, so the flow stops mid-request until the policy is read.
Fix — read the posture, enable the channel, then re-dispatch:
  1. Read the current policy with GET /api/v1/compliance/archival. The response is always 200 and returns the recorded channels list — the exact posture the export gate crosses on every call.
  2. If the channel is missing — or enabled is false so the list never applies — upsert the policy with PUT /api/v1/compliance/archival, including the channel in channels (owner/admin role required for the write).
  3. Re-issue the same POST /api/v1/compliance/archival/export once. The gate re-reads the policy on every call, so the same export passes the moment the channel is covered.
The rest of the archival surface — destinations, WORM immutability and retention-lock windows, legal-hold flags, and the export executor — is documented on the Archival & export page. For the recording-side hold workflow a legal-hold flow often pairs with, see Recording integrity, legal hold, and QC failures.

​
What not to do

  • Do not re-file the request before reading the policy. The 409 response only tells you the named channel was not covered; it does not tell you which channels ARE. Issue the same export again only after GET /compliance/archival returns a channels list that covers the channel — re-filing blind replays the same refuse.
  • Do not retry in a loop. The gate is deterministic — it re-reads the policy on every attempt and refuses until the channel is enabled. Loop retries burn your export rate-limit budget without moving the posture.
  • Do not disable a contact’s freeze just to clear a send. The archived-stage freeze exists to guarantee the record stays put; if the freeze is in scope (retention, legal-hold), route the send around it rather than unarchiving it. Unarchive only when you deliberately want the row back in the active funnel.
  • Do not ask for a second opinion from the error. The named channel on the 409 and the lifecycle_stage on the contact row are the answer — read them, fix the posture once, and re-dispatch.

​
See also