#749·himalaya

feat: add a shared draft lifecycle API

Author: trashhaloCreated Sep 15, 2026Updated Sep 15, 2026

Why

Frontends that support drafts need one portable lifecycle. The shared message add --mailbox drafts --flag draft path works for mailbox-backed backends, but a Gmail REST account rejects it with Gmail does not support adding messages, because Gmail drafts are a separate resource.

That leaves every frontend to discover backend-specific draft behavior and branch around it, despite drafts being a common mail workflow.

What

Add a shared draft command family that maps a common lifecycle to each backend's native semantics:

  • draft create
  • draft update <id>
  • draft delete <id>
  • draft send <id>

The commands would accept the same raw RFC 5322 input as the existing message operations and return a stable draft ID in JSON. A Gmail backend could use users.drafts; mailbox-backed backends could store the message in the configured Drafts mailbox.

Scope / non-goals

This would not replace protocol-specific APIs or try to erase provider-specific message models. It would provide the shared draft lifecycle frontends need, so they do not require backend-specific branches for an ordinary compose/save/send flow.