Skip to main content

chainmail watch

Stream mail events from the daemon's event log: one JSON line per event, or one human line per event on a terminal.

Where the stream starts:

--group NAME   after the group's acknowledged event. Each line is
               acknowledged once it is written, so a restarted watcher
               misses nothing. A new group starts at the newest event.
               Delivery is at least once.
--since ID     after this event ID.
neither        with events from now on.

Filters apply in the daemon. status and gap events pass a --kind filter unless --kind names them. --in matches a folder or a Gmail label, and inbox also matches \Inbox.

Work item events are sent only when asked for: item, a change to a work item, and item_mail, new mail on a thread linked to one, come when --kind names them or --item is given. --item ID limits both to that item and every item below it, and leaves out new, flags and expunged events.

The watch reconnects by itself when the daemon goes away, or sends nothing for 75 seconds, resuming from its group or from the last event or heartbeat it saw. It stops with an error only when the daemon refuses the request, such as a bad group name or an unknown account. An account that needs a login does not stop it: the watch goes on, and an auth_required status event says what to run. --once stops at the first heartbeat, which comes once every event already in the log has been printed.

Subjects, names and addresses in new and item_mail events come from the message and are untrusted.

Usage​

chainmail watch [--group NAME | --since ID] [--account NAME]... [--kind KIND[,KIND]...] [--in FOLDER] [--item ID] [--once] [--heartbeat] [flags]

Examples​

# resume where the triage group left off, new mail only
chainmail watch --group triage --kind new
# print everything logged for one inbox, then exit
chainmail watch --since 0 --account work --in inbox --once
# changes to an item and the items below it, and new mail on their threads
chainmail watch --kind item,item_mail --item it_01jcb7m2k9r8q3v4w5x6y7z8a9

Flags​

      --account stringArray   only this account; repeat for more (default: all)
      --group string          resume after this group's acknowledged event, and acknowledge each line once written
      --heartbeat             print heartbeats too
      --in string             only this folder or Gmail label, such as inbox (default: all)
      --item string           only item and item_mail events of this item and every item below it
      --kind strings          only these kinds, comma separated: new, flags, expunged, status, gap, item, item_mail (default: all but item and item_mail; with --item: item, item_mail, status and gap)
      --once                  exit at the first heartbeat, once every event already in the log is printed
      --since int             resume after this event ID

Global flags​

      --output string   output format: json or table (default $CHAINMAIL_OUTPUT, then cli.toml, then table on a terminal, json otherwise)
      --socket string   daemon socket (default $CHAINMAIL_SOCKET, then cli.toml, then /run/chainmail/chainmail.sock)

Commands​

See also​