Compose

Compose is Herald’s writing screen. It supports normal message composition, replies, forwards, CC/BCC, Markdown preview, file attachments, address autocomplete, draft auto-save, AI rewrite assistance, AI subject suggestions, and send error recovery.

Overview

Press 2 to open Compose. Compose sends through the configured SMTP server and can be opened directly or pre-filled by Timeline reply, Timeline forward, or quick reply workflows.

Screen Anatomy

Area	What it shows
To field	Primary recipients. Autocomplete searches contacts once the current token has enough characters.
CC field	Carbon-copy recipients with the same autocomplete behavior.
BCC field	Blind-copy recipients with the same autocomplete behavior.
Subject field	Message subject and optional AI-generated subject hint.
Body field	Markdown-capable message body.
Markdown preview	Rendered body preview using Glamour when `ctrl+p` is active.
Attachment lines	Attached file paths or filenames after files are added.
Attachment path prompt	One-line path input opened by `ctrl+a`.
Autocomplete dropdown	Up to several contact suggestions with selected row and hidden-count note when compressed.
AI assistant panel	Custom prompt input, quick rewrite actions, generated response, and accept behavior.
Compose status	Validation errors, send state, AI messages, attachment errors, and draft status.

Controls

Key	Context	Preconditions	Result
`tab`	Compose fields	No autocomplete selection is being accepted and no subject hint is pending.	Moves focus To -> CC -> BCC -> Subject -> Body -> To.
`tab`	Subject hint	AI subject hint is visible.	Accepts the suggested subject.
`ctrl+s`	Compose	SMTP configured, To not empty, Subject not empty.	Sends the message with Markdown-derived HTML/plain text and attachments.
`ctrl+p`	Compose	Any draft.	Toggles Markdown preview.
`ctrl+a`	Compose	Attachment prompt not already active.	Opens file path input for adding an attachment.
`enter`	Attachment prompt	Attachment prompt active.	Adds the expanded path as an attachment.
`esc`	Attachment prompt	Attachment prompt active.	Cancels attachment input.
`ctrl+g`	Compose	AI backend configured.	Opens or closes the AI assistant panel.
`enter`	AI prompt field	AI assistant prompt has text.	Sends the custom instruction to the AI assistant.
`1` to `5`	AI panel	AI panel open and body is not empty.	Runs quick actions: improve, shorten, lengthen, formal, or casual.
`ctrl+enter`	AI panel	AI response is available.	Replaces the body with the AI response and closes the panel.
`ctrl+j`	Compose	AI configured and body or reply context exists.	Requests an AI subject suggestion.
`esc`	Compose	Subject hint, AI panel, or compose status is active.	Clears the subject hint, closes AI panel, or clears status.
`up` / `down`	Autocomplete dropdown	Suggestions are visible.	Moves the selected suggestion.
`enter` / `tab`	Autocomplete dropdown	Suggestions are visible.	Accepts the selected suggestion into the active address field.
`esc`	Autocomplete dropdown	Suggestions are visible.	Dismisses suggestions.
`1` / `3` / `4`	Compose tab	Main Compose handler active.	Switches to Timeline, Cleanup, or Contacts.

Workflows

Send a New Message

Press 2.
Enter at least one To recipient.
Press tab through CC, BCC, Subject, and Body as needed.
Write the body.
Press ctrl+p to inspect Markdown rendering when desired.
Press ctrl+s.

Add an Attachment

Press ctrl+a.
Type or paste a file path. ~ is expanded.
Press enter.
Confirm the attachment line appears.
Send normally.

Use Address Autocomplete

Type part of a name or email in To, CC, or BCC.
When suggestions appear, use up/down to select.
Press enter or tab to insert the contact.
Continue typing more recipients.

Use AI Writing Assistance

Write body text first.
Press ctrl+g.
Press 1 through 5 for a built-in rewrite or type a custom instruction and press enter.
Review the AI response.
Press ctrl+enter to accept it into the body, or esc to close the panel.

Reply or Forward From Timeline

In Timeline, select a message.
Press R to reply or F to forward.
Compose opens with recipient, subject, and body context pre-filled.
Finish the message and press ctrl+s.

States

State	What happens
Empty required fields	`ctrl+s` reports a send error when To or Subject is empty.
SMTP not configured	Send reports that SMTP is unavailable.
Markdown preview	Body is rendered as styled preview rather than the edit textarea.
Attachment input	Key input is captured by the path prompt until `enter` or `esc`.
Large attachment warning	Attachment add flow can warn when a file is larger than the configured threshold.
Autocomplete compact	Suggestions collapse to a single line when vertical space is tight.
AI unavailable	`ctrl+g` and `ctrl+j` report no AI backend configured.
AI loading	The assistant waits for provider output and then displays a response.
Draft saved	Compose auto-saves drafts about every 30 seconds when there is content.
Send success	Fields clear, saved draft is deleted, and status reports send success.
Send error	Draft content remains available so you can fix configuration or message fields.

Data And Privacy

Compose reads contacts for autocomplete and writes drafts through Herald’s backend. Sending uses SMTP credentials from config and sends the full message, recipients, Markdown-derived bodies, and attachments to the SMTP server. AI assistance sends draft text and optional reply context to the configured AI backend. Attached files are read from local disk when added or sent.

Troubleshooting

If autocomplete does not appear, keep typing until the current token is long enough and confirm contacts have been imported or learned from mail.

If ctrl+s does not send, read the compose status for missing To, missing Subject, SMTP configuration, or provider errors.

If an AI subject suggestion appears but you do not want it, press esc. If you do want it, press tab.

If a send error occurs after attaching files, verify the file still exists and that your provider accepts the message size.