Work with drafts

An Alcarta draft is a real message in the provider’s Drafts folder. A person can open and edit it in another mail client. Alcarta tracks the provider message with a drf_… row, a revision, and hashes; it does not treat a database copy as canonical.

Create and edit

Use start_draft for a new message or reply_to_thread for a reply with derived thread headers. Choose one editing style:

• edit_draft replaces the addressable headers, body, and attachments as a complete revision.
• patch_draft applies header operations and search-and-replace blocks to the body.

Every mutation must name the expected revision and hashes. If another client changed the draft, Alcarta returns 409 draft_conflict with the current revision and body so the caller can rebase. There is no force flag and no last-write-wins mode.

An empty patch_draft is a read: it relocates the provider draft and refreshes the tracked state without changing content.

Request a send

wants_to_send_draft snapshots both the body hash and addressable-header hash. The review page shows the complete outgoing body, recipients, attachments, and hashes. Immediately before SMTP or JMAP submission, Alcarta checks both hashes again.

While a send request is live, content edits return draft_locked. Discarding is still allowed while the request is pending: it cancels the request and removes the provider draft. Once submission has begun, discard is refused.

Direct send is intentionally narrow

send_draft is not included in any scope group. It must be granted explicitly. A mailbox whose require_approval_for_send setting is on—the default—still requires an approved request even when the caller holds send_draft.

Unknown send outcome

Alcarta writes a submission marker before the irreversible provider call. If a crash leaves the outcome unknowable, the draft is treated as sent and the request fails with send_outcome_unknown. Alcarta does not retry and risk sending a duplicate. Check the provider’s Sent folder to resolve the ambiguity.