Plugins

Plugins (experimental)

TideMail can run external plugins placed in $XDG_CONFIG_HOME/tidemail/plugins/ (or ~/.config/tidemail/plugins/ when XDG_CONFIG_HOME is unset). When any are installed, the command palette (:) gains Plugins (experimental), a read-only list of installed plugins, and Run plugin. Plugins receive a message's sender, recipients, subject, date, and flags, never its body, and they never change your mail. The one exception is a PGP plugin, which you install for that purpose (see PGP encryption and signing).

Installing plugins. Open Settings → Plugins (or the command palette's Browse available plugins…) and press b to list the official plugins from the tidemail-plugins repository. Select one and press i to install it, u to update it when a newer version exists, or x to remove an installed one. TideMail asks first and shows what the plugin will be able to do; it downloads from GitHub, checks the release's checksum, and never runs the plugin while installing. The new plugin appears in the list straight away, with automatic processing still off. The list is fetched only when you open it. Plugins from elsewhere can still be copied into the plugins directory by hand.

Run plugin runs a plugin you choose on mail, whether or not it has already been classified, for example after updating a plugin or changing its settings. Press p in the message list or reader, or use the command palette. The picker lists each plugin by name with a short description of what it does; you pick once:

• Run plugin on current message… runs it on the message you are on and opens a result card that explains what the plugin found in plain words: for example Newsletter · low priority, followed by a short Why. Type, priority, confidence, raw tags, and technical information live under d Details; press d again to go back and Enter or Esc to close. When TideMail itself finds an unsubscribe option in the message, the card says Available — press u. u uses the same safe flow as Ctrl+U in the reader: TideMail shows the destination and requires confirmation before a web unsubscribe, or opens a prefilled unsubscribe draft for email links. Otherwise the card says No unsubscribe option. The plugin never receives the unsubscribe link and cannot unsubscribe on its own. If the plugin found nothing new, the card says No changes; if it failed or took too long, the card says so in plain words, with the technical reason under Details.
• With messages selected (Space), the same command reads Run plugin on N selected messages… and runs on the selection (asking first for 10 or more).
• Run plugin on all N messages in Inbox… (or the current folder, Unified Inbox, search results, Needs You, Waiting on Them, or Snoozed) runs on every message the list currently shows. It always asks first, with the count. Only mail already in TideMail's cache is used; nothing is downloaded.

After you have run a plugin, the palette also offers Run name again, which skips the picker.

Several messages run one at a time, with progress on the status line (running on 312 messages in Inbox… 87 / 312), and end with one summary card: how many were processed, changed, unchanged, or failed, and what the plugin found (for example Newsletter 9, Automated sender 2). Failure reasons are under Details. A failing message does not stop the run, and its earlier annotations are kept. Cancel plugin run in the palette stops a run; quitting TideMail stops it too. The run works whether or not the plugin processes new mail automatically, and does not affect that.

A plugin that also declares the annotations permission can attach short notes to a message, such as "needs reply" or "category: github". TideMail stores them in its local cache and shows them as tags in message rows, the same way in every folder and view: ↩ REPLY, ! URGENT, ◆ IMPORTANT, and the category name (GITHUB). On narrower screens tags shrink to their symbols, with the category becoming a single glyph chosen for that category (↩ ◆ ⚙ for github), then to a plain #github, or disappear before the subject does. Each plugin run replaces that plugin's notes on the message; a successful run with nothing to say clears them. Message annotations in the palette lists all of a message's annotations. Running a plugin can move messages into or out of Needs You at once; snoozed messages stay snoozed, and Waiting on Them does not use annotations.

With a message highlighted or open, press e to edit its tags. You can also search the command palette for Edit tags / Correct classification, or press e in Message annotations. Use ↑/↓ to choose a field, ←/→ to choose a value, and Enter to save it. You can correct needs reply, urgency, importance, or category. A correction overrides every plugin for that field, while the original plugin annotations remain visible. Use plugin decision or Reset all corrections removes the local decision. Corrections survive plugin reruns, annotation cleanup, and plugin removal. They never leave your computer: they are not sent to Jev, TypeSafe, or any plugin with a message. The one exception is report plugins that declare permission to read classifications (annotations_query and analytics_read). Those can see a message's current classification, including that it came from your correction. Reports with analytics_read also see corrected categories as part of category totals.

Choose how tags look under Settings → Display → Appearance → Annotation Tags:

• Tag style: use ←/→ on the single picker to choose Pills (Square), Pills (Round), Pills (None), Compact, Plain, or Glyph Pills (Round). The picker names and previews every choice. Square pills pad each side, Round uses rounded caps (needs a Nerd Font), and None removes the padding. Compact uses colored text such as ↩REPLY #github; Plain uses uncolored [REPLY] [github]. Glyph Pills (Round) shows only the matching category glyph (for example, ⚙ for GitHub or ✉ for newsletters) inside rounded colored pills, even when full labels would fit. Unknown categories use ●; disabling icons uses ASCII markers. On narrow rows the caps may drop to preserve subject space.
• Tag colors opens an editor for the background and foreground of each tag: needs reply, urgency, importance, the default category color, and the known categories (github, shipping, security, calendar, newsletter, support, social, billing, receipt, notification, personal). Other categories use the default category color. Select a tag and press b or f to open a visual color picker for that swatch: tab moves between the RGB sliders (or the HSL field in HSL mode, toggled with m) and the hex/R/G/B/H/S/L fields, ↑↓←→ adjust whatever has focus, and enter on a field types an exact number while enter elsewhere applies the color and returns to the list. # jumps straight to typing a hex value, y copies the current hex to the clipboard, and esc cancels without changing anything. Press r on a tag to reset both its colors to follow the theme. Changes apply and save the moment you confirm; colors you do not set follow the theme, and plugins can never choose colors.

Annotations stay after you remove a plugin, so its tags remain until you clear them. In Message annotations, select a plugin and press c to clear its annotations from that message, or C to clear all of them. In Plugins (experimental), select a plugin (including one listed under Stored data from removed plugins) and press c to clear everything it stored. TideMail asks before clearing, and clearing never deletes or changes your mail.

A plugin can also process new mail automatically, if it supports that and you turn it on: in Plugins (experimental), select it and press a, then confirm. It then receives the same metadata (never message bodies) for each newly arrived unread message, and its tags appear as mail comes in. Old mail, first-time setup of an account, and loading older messages are never sent. The plugin list shows its current queue, running state, dropped events, failures, last success, last failure, and a sanitized last error when those values exist. Three consecutive automatic failures pause that plugin; press r on it to resume. Manual Run plugin actions remain available while automatic processing is paused.

Each plugin's entry in Plugins (experimental) reads like a short product page: its name and description, its permissions as a checklist in plain words (✓ Message details, ✓ Save tags, ✗ Message body, ✗ Network), and whether Automatic processing is on.

Automatic processing is off for every plugin until you enable it. A plugin that fails three times in a row is paused; select it and press r to resume.

Some plugins are reports, such as mail analytics. The plugin list shows enter run report for them: select one in Settings → Plugins or Plugins (experimental) and press enter. The report opens in the plugin result window when it finishes; closing a report launched from Settings returns to the Plugins section. Press r in the plugin list to reopen the last result. Reports can be charts as well as text: stat tiles, sparklines, bar charts, heatmaps, and tables, drawn in your theme. Category bars use your category tag colors, so changing those under Settings → Display → Appearance changes the charts too. Scroll with ↑/↓. To answer, a report asks TideMail read-only questions, only those its permissions allow (the list shows them): for example message counts per day, category totals, or a list of conversations. TideMail answers from its local cache. A report never sees message bodies, cannot change your mail or TideMail's state, and cannot draw its own screens or colors. If a folder or account is selected in the sidebar, the report can treat it as the current one.

Open Settings → Plugins to administer plugins directly in the right-hand pane. Press → to focus the list, ↑/↓ to select a plugin, and s to edit its settings in the same pane. The list also offers automatic-processing, resume, and stored-data controls when available. In a plugin form, esc returns to the list; from the list, esc returns to the Settings sidebar. Tab also returns to the sidebar when you are not typing a secret. Plugin changes save immediately. The command palette's Plugins (experimental) view still offers s to open a plugin's settings. Secret values such as API keys are stored in your system keychain, never in config.toml, and are shown only as ************. A secret must be at least 6 characters, so it can be masked in plugin output. Plugins are separate programs, not part of TideMail's mail handling: for example, TideMail Smart (JEV) (an external plugin) can call TypeSafe's Jev model over the network, and its settings describe exactly what it sends.

Plugin support is experimental. Only install plugins you trust. To write a plugin, see plugins.md and the Plugin API v1 docs in plugins/.

---

Source in TideMail at 65f889c