Compose and Drafts

Herald lets you draft, edit, and send messages. Drafts are stored locally and synced to the server. Attachments can be dragged, dropped, or pasted.

Draft lifecycle

A draft is a work-in-progress message. ComposeDraft (HeraldKit/Sources/HeraldKit/Compose/ComposeDraft.swift:29) represents it:

• Local draft — User starts composing; the draft is created locally via ComposeDraft.
• Save to server — OutboxService (HeraldKit/Sources/HeraldKit/Compose/OutboxService.swift) uploads the draft to HQBase.
• Sync back — The server returns a draft id; Herald stores it locally in MailStore as a CachedDraft.
• Edit — User makes changes; ComposeViewModel (Herald/Compose/ComposeViewModel.swift:16) manages the local state.
• Send — User clicks Send; OutboxService transmits the message to the server, deleting the draft.

ComposeViewModel autosaves to the server after a short debounce, so a crash mid-compose loses at most the last few seconds of typing; the saved draft reappears in the Drafts folder on relaunch. A draft with an open composer is protected from being overwritten or removed by a poll.

Attachment handling

Attachments are managed via AttachmentPasteboard (HeraldKit/Sources/HeraldKit/Compose/AttachmentPasteboard.swift:42), which reads files and images from the macOS pasteboard.

AttachmentLimits (HeraldKit/Sources/HeraldKit/Compose/AttachmentLimits.swift:13) enforces size and count limits (per HQBase spec).

Attachments upload to the draft as they are added (chips show a spinner and a cancel control); Send waits for queued uploads to finish. Limits match the server exactly: 25 MiB per file, 25 MiB per draft, 20 files.

Outbox service

OutboxService (HeraldKit/Sources/HeraldKit/Compose/OutboxService.swift) is an actor that:

• Queues outgoing messages
• Uploads attachments
• Transmits messages to the server
• Deletes drafts on success
• Reports errors and retries on transient failures

The app displays pending uploads and transmission errors in real-time.

---

Last updated: 2026-08-19 — compose and drafts; fact-checked against the code for v0.3.0