Labels and filters
Labels and filters
Account chips
Messages carry accountId, accountName and accountEmail. The unified view shows a deterministic color label per connected address, and the account bar filters by address. This is address-level labeling, not alias-level labeling.
Custom labels
Custom labels are separate and user-defined, shared across accounts. They can be created from the sidebar or from the filter editor.
Clicking a label opens a label view: the API reads message_labels, groups the assigned message ids by account and folder, fetches those IMAP UIDs directly from the provider and merges them with relay messages. The view therefore covers Inbox, Sent, Drafts and Spam across the selected accounts, like Gmail, without mirroring the whole mailbox locally. Removed or expunged messages simply disappear from the view.
When a message moves to another folder on the provider, its UID changes and the local label assignment no longer applies. The optional IMAP metadata sync mirrors headers and UIDs, but labels still follow the UID, so a move can lose the local assignment until the message is labeled again.
Incoming labels
Each account can define an incoming_label_id. When the inbox is listed, every incoming message of that account receives the shared label automatically. The label is chosen while adding the account or in Settings; if it does not exist, it is created.
Filters
Automatic filtering is managed in Settings → Filters and is shared across accounts.
- Criteria are ANDed and matching is case-insensitive.
- Match fields: From, To, Subject, words, words that must not appear, and attachment presence.
- Actions can apply one or more labels, forward to recipients, or both, like Gmail.
- Matching runs when the inbox is listed and when the cron worker syncs new inbox messages.
- The match text covers sender, recipients, subject and snippet, not the full body.
Forwarding uses the original EML, attaches it as message/rfc822 and stamps X-WhelkMail-Forwarded to prevent loops. See Forwarding and cleanup.
Contacts
Contacts are a shared address book: id, name, email, note, created_at. A unique index on lower(email) prevents duplicates; creating a contact with an existing email updates the name/note instead. Contacts are not account-scoped.
The UI supports search, create/edit/delete, CSV import/export, and autocomplete in To/Cc/Bcc.
Signatures
signature_mode is shared (default) or per_account:
shared:default_signatureis used for every account andaccounts.signatureis ignored.per_account: every account uses its ownaccounts.signature; an empty value means no signature.
Conversations and labels
Label views and search results are grouped into conversations like the standard folders: a label view loads the whole conversation for the conversations that carry the label, and search collapses the matching messages of a thread into one row whose count refers to the matches on that page.