Conversation Lifecycle

See also Bug 789078.

Geary is currently somewhat inconsistent and incomplete in how it lets people manage the lifecycle and labelling of conversations. This is in part due due to trying to fit the conversation model to both IMAP and GMail, and part due to feature growth over the years. We should tidy this up to make it both consistent and complete.

Based on some notes I made, conversations seem to exist in two different finite state machines — one that covers the overall conversation life-cycle, and one that covers labelling of conversations that are not trashed, junked, etc. States sometimes represent mailboxes, but sometimes are an abstract state, and the transitions between these states define the actions that people might want to take. These actions should be made available to people as high-level UI items, and Geary should manage the implications of the actions under the hood.

Use cases:

  1. Alice has a conversation with both sent and received messages in the Inbox that she has finished with. She wants it out of the Inbox so she hits Archive.
  2. Bob receives a work message, so labels it as Work but stays in the Inbox. On completing the important task, he wants it out of the Inbox so he hits Archive, but wants it to remain labelled as Work.
  3. Charlie has an elaborate hierarchy of mailboxes and wants to move a received message in the Inbox to one of these.
  4. Dave receive the same spam message twice and wants to move both to the Junk folder.
  5. Erin replies to a mailing list message early on but loses interest in the conversation later as it goes off topic. Earlier messages (including her sent messages) are archived but she wants latter messages to be moved to the trash.

Lifecycle FSM

The lifecycle FSM defines the overall state that a conversation exists in. These states apply to the entire conversation, and transitions between states mostly involve moving messages in a conversation to special-use mailboxes. Since a state applies to the entire conversation, these actions move all copies of all messages in the conversation, not just those in the currently selected mailbox in the client.


  • Normal - a compound state that encapsulates label managing (see Labelling FSM below)

  • Trash
  • Junk
  • Deleted - the terminal state


These operate on all copies of all messages in the conversations, including those in Sent and with multiple copies in multiple folders.

Moves the conversation to the trash
Moves the conversation to the Junk
Restore all messages to their previous states/folders (difficult to implement)
Permanently deletes all messages in the conversation

Note: This definition of Trash doesn't work with use case #5 - all messages will be deleted, including those sent and already archived. However that could be covered with the ability to "Mute" a conversation, i.e. Bug 713237

Labelling FSM

The labelling FSM manages labels for conversations that are in the Normal lifecycle state. A conversation's labelling state depends on the mailboxes that it has messages in. This FSM needs to be flexible enough to handle different server models (IMAP vs Gmail IMAP) and different user workflows (pile, file, hybrids). Unlike for lifecycle transitions, labelling transitions typically involves moving messages only between Archive and Inbox or copying to user-defined mailboxes.


  • Active - at least one message in the Inbox, optionally Sent and Archive, but no user defined mailboxes
  • Active Labelled - at least one message in Inbox, optionally Sent and Archive, and one or more user defined mailboxes
  • Archived - messages in Archive and/or Sent only
  • Archived Labelled - messages in one or more user defined mailboxes, optionally Archive and Sent, none in Inbox


Move all messages in the Inbox to the Archive folder
Move most recently received message to Inbox
Copy all messages not already fully labelled to user defined mailboxes for each label, remove any in Archive
Copy/move all messages not in Archive to Inbox, remove from any user defined mailboxes
Archive labelled
Copy all messages not already fully labelled to user defined mailboxes for each label, remove any in Inbox or Archive
Restore labelled
Copy most recently received message to Inbox
Label archived
Copy all messages not already fully labelled to user defined mailboxes for each label, remove any in Archive
Unlabel archived
Copy/move all messages in user defined mailboxes to Archive, remove from all user defined mailboxes

None of these transitions should have any effect on messages in Sent, since that is effectively an immutable user label.

File Operations vs Labelling

We can implement labelling a conversation as moving it to a user defined mailbox, taking care of use case #2, and reserve moving for changing its state, e.g. Archiving, Trashing, Junking, etc, taking care of use case #1, however this still leaves use case #3. That can perhaps be taken care of by a Archive-As action, which does either simple move to a user defined mailbox, or does a copy-and-archive.

Labelling a conversation corresponds to copying it to a user defined folder, which takes care of use case #2, where as moving corresponds

User Experience

Both conversations and messages should be tagged with their current mailboxes. Messages with the individual mailboxes they belong to, and conversations with the union of all tags, except Sent and Archive. See Bug 713027.

A conversation's current state defines what UI is presented to the user when it is selected. E.g. in the Archive state these actions should be available: Restore and Label (from Labelling FSM), and Trash and Junk (from the Lifecycle FSM).

Archive and Trash are primary action for conversations in the Inbox and so they should probably be emphasised and easily activated via the UI.

The Restore action is the only primary action for most other states, and hence that should be similarly emphasised, although implementing this properly will be tricky, e.g. to ensure that sent mail in the conversation is restored to Sent, and received mail in the conversation is restored to whatever other mailbox(es) it was in.

The mock-up below shows what different toolbars/actionbars might lookup under this scheme for various folders:

These correspond to the following folders:

  1. Inbox
  2. Archive/user-defined folders
  3. Drafts
  4. Trash
  5. Junk

Trash uses an icon rather than a text label since linked buttons with different label types looks pretty inconsistent.

Sent isn't shown, but would be similar to (1) or (2) but without a primary action button or Junk button.


Since new messages can be added to a conversation as they arrive, and since users can move/copy individual messages in other MUAs, we need to work how this effects the states above.

Also need to work out how well this fits with GMail (e.g. Bug 712963)


Comments welcome, either below here or on the mailing list.

Apps/Geary/Design/ConversationLifecycle (last edited 2018-07-03 04:41:23 by MichaelGratton)