Correspondence

Every POST /plans/{plan_id}/runs call creates correspondence. The plan owns the workflow definition; the correspondence records this execution.

List and filter runs

GET https://api.keepable.co/sender/v2/correspondence?plan_id=pln_01J8ZQ4T&status=live&limit=50
Authorization: Bearer {{KEEPABLE_TOKEN}}

The list can filter by plan_id, kind, content_type, status, lens, or free text. Use the opaque next_cursor to paginate.

Read one current record with:

GET https://api.keepable.co/sender/v2/correspondence/cor_01J8ZQ4T
Authorization: Bearer {{KEEPABLE_TOKEN}}

status is live, sealed, or withdrawn. rollup and status_label give the audience-level outcome without making you count a page of participants.

Participant outcomes

GET https://api.keepable.co/sender/v2/correspondence/cor_01J8ZQ4T/participants?limit=100
Authorization: Bearer {{KEEPABLE_TOKEN}}

The response carries the page, a full counts rollup, and next_cursor. Filter by state or search by name or your ref when investigating one recipient.

The run endpoint answers 202 before asynchronous delivery finishes. Prefer webhooks for state changes and use these reads for reconciliation or recovery.

Withdraw a run

POST https://api.keepable.co/sender/v2/correspondence/cor_01J8ZQ4T/withdraw
Authorization: Bearer {{KEEPABLE_TOKEN}}
Idempotency-Key: 60fb96d0-34c5-4270-8354-b7b0dfe05677
Content-Type: application/json

{ "reason": "The upstream instruction was cancelled." }

Withdrawal stops everything still pending: undelivered copies, open questions, unsigned invitations, and unclaimed codes. It does not erase the record.

If any participant has already received the file, the call returns 409 already_delivered and changes nothing. What arrived is theirs, and no scope relaxes that rule.