Stop a UnifyPort Runtime Without Your Recovery Worker Restarting It

To temporarily stop a UnifyPort messaging account’s connection without deleting the account, call POST /v1/accounts/{account_id}/runtime/stop with {}. Confirm runtime_status: stopped; stopping still needs reconciliation. Before doing this, tell your application’s recovery workers that the stop is intentional. Otherwise, a worker designed to restore offline accounts may start the connection again.

Key takeaways

• Runtime stop preserves the account; it is not account deletion.
• Store the intended pause in your application before stopping the connection.
• Observed runtime_status and permission to recover are different decisions.
• Restarting does not prove that messages from the stopped interval were recovered.

The race: a correct recovery action at the wrong time

Consider this hypothetical sequence: an operator stops a messaging account for planned maintenance, a health worker reads stopped, and the worker calls start because its job is to keep accounts online. Both requests can match their individual API contracts while contradicting the operator’s intention.

The solution is not another authentication attempt. It is a shared application-side decision about whether this account should currently be connected. The existing runtime recovery runbook explains how to recover a connection that should be online. A planned stop adds a gate before that recovery logic.

Do not confuse this gate with an undocumented API setting. The account lifecycle reference separates account status, authentication state, and runtime_status. The local pause record proposed here is your application’s own data, not an additional UnifyPort field or a promised behavior of account status.

First choose what actually needs to stop

Intended outcome	Appropriate boundary
Pause CRM writes or AI processing while continuing message intake	Pause your application consumers
Stop this account’s live connection but retain the account	Stop runtime
Retire the messaging account resource	Separate account deletion workflow

If only downstream processing needs maintenance, use the webhook maintenance comparison. Stopping the connection is not a durable buffering strategy.

Likewise, use the account deletion guide only when retirement is intended. The runtime stop contract does not establish a refund, subscription pause, native-account deletion, or erasure of stored messages.

Make the pause visible before issuing the stop

Recommended application procedure:

1. Capture the selected workspace, account_id, provider, operator, and reason. Read the account and its authentication state separately.
2. Save a durable local pause decision for this account. Make recovery workers and scheduled send workers consult it before dispatching new operations.
3. Coordinate with workers already running. A flag written now cannot cancel an API request already sent. Use your own per-account coordination and explicitly reconcile operations already in flight.
4. Keep the webhook receiver available to verify and store events that still arrive. Do not interpret runtime stop as a documented drain of webhook deliveries.
5. Submit one reviewed stop request, then inspect the result.

A minimal control rule is shown below. This is application pseudocode, not SDK syntax or a new endpoint:

before an automatic start or reconnect:
    read the account's current local operating intent
    if an operator has paused it:
        do not dispatch recovery
    otherwise:
        inspect authentication and runtime state
        select the documented recovery action

Every recovery path needs the same gate, including delayed jobs and manual recovery buttons. Coordinate pause and resume changes so an old queued start does not become valid merely because a later operator has changed the screen.

Stop once, then reconcile what happened

The Stop runtime reference documents the empty JSON body. This illustrative request has not been executed here. Populate the variables from your backend’s reviewed account selection and protected API-key configuration:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/runtime/stop" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

Keep the API key server-side. Record HTTP status and available request diagnostics without logging secrets.

Observation	Interpretation and next step
runtime_status: stopped	Stop is complete at the runtime layer; keep the local pause decision
runtime_status: stopping	A transition is in progress; check state again
Timeout or unreadable response	Outcome is unknown; read state before another mutation
Runtime becomes running while locally paused	Investigate competing start or reconnect paths; do not report maintenance complete

Use Get account or Refresh runtime state for reconciliation. Refresh synchronizes state; it does not request a restart. Apply a bounded checking and escalation policy in your application rather than inventing a completion deadline.

Do not wait for an invented account.stopped event. The lifecycle reference says account.status.updated is not guaranteed for every requested transition. A quiet inbox is not proof that the runtime stopped.

Resume as a separate, reviewed transition

Keep outbound work gated while you check the retained account’s current authentication state. If user action is required, continue the documented authorization flow; successful authorization normally starts the runtime, so do not begin reauthorization during a pause unless that is intentional.

If the runtime is stopped and authorization remains valid, use Start runtime. Coordinate this explicit resume with the same local controls used for pausing. Reconcile until the connection is actually running; a starting response is not completion.

Before releasing accumulated jobs, review whether each job is still relevant. Send a controlled test message and trace fresh intake through verification and storage. Only then re-enable the intended consumers and automatic recovery policy.

UnifyPort’s unofficial interface does not guarantee replay of missed payloads or provide a general REST message-history read API. Record the stopped interval as a possible collection gap. A successful fresh test proves the resumed path, not recovery of that gap.

FAQ

Does stop delete the messaging account?

No. The documented action stops the runtime without deleting the account. Starting it again is a separate action.

Should a health worker start every stopped account?

No. First check whether your application currently intends that account to be online. Runtime state alone does not express operator intent.

Does a successful stop cancel queued replies or webhook deliveries?

Do not assume so. Manage application jobs separately; the public stop contract does not promise cancellation of already submitted work or a webhook drain.

Does stopping pause billing?

The runtime stop contract makes no such promise. Do not use a connection-state response as evidence of a financial change.

Next step and sources

Implement the local recovery gate alongside Stop runtime. Proposed acceptance checks include a competing recovery worker, an in-flight start, a lost stop response, stopping, a deliberate resume, and a stale queued reply. These are tests to perform, not reported results.

References checked on 2026-11-04:

• UnifyPort: Stop runtime
• UnifyPort: Account lifecycle
• UnifyPort: Webhook delivery and recovery limits