Plugin overview

Plugins (experimental)

TideMail can run external plugins that classify mail from its metadata and attach annotations such as needs_reply=true or category=billing. TideMail stores the annotations, shows them as tags in message rows, and uses them for views like Needs You. Plugins never change mail, and nothing a plugin returns is treated as an instruction.

• A plugin is an external executable plus a plugin.toml manifest, installed in $XDG_CONFIG_HOME/tidemail/plugins/<name>/ (or ~/.config/tidemail/plugins/<name>/ when XDG_CONFIG_HOME is unset).
• TideMail writes one JSON request to its stdin; it writes one JSON response to stdout. Any language works.
• Plugins receive header-level metadata only (sender, recipients, subject, date, flags), never passwords or tokens. The one exception is a cryptography plugin that declares message_raw or message_compose: it is handed the encrypted or signed part of a message you open, or the content of a message you send with Sign or Encrypt on.
• Report plugins can ask TideMail read-only, allowlisted queries (message and thread lists, stored annotations, aggregate analytics). TideMail runs them itself; plugins never get database access.
• Plugins provide semantics; TideMail controls presentation. Tag styles and colors come from the user's settings and theme, never from a plugin.
• Plugins are not sandboxed by the operating system. Only install plugins you trust.

For users

How to run plugins (Run plugin), read and clear annotations, turn on automatic processing, change plugin settings, and pick tag styles and colors: see the user guide, guide.md › Plugins.

For plugin authors: Plugin API v1

The developer documentation is in docs/plugins/:

Page	Covers
README	overview and architecture
getting-started	build your first plugin, step by step
manifest	plugin.toml fields and discovery
protocol	envelopes, methods, metadata, stdout/stderr
permissions	what each permission allows
presentation	explaining results to people
annotations	limits, replace-on-success, conventional keys, reclassification
events	message.received for new mail
settings	bool/select/secret settings and plugin.test
queries	report.run and read-only queries
analytics	aggregate statistics
views	structured report views drawn in the user's theme
security	trust model and runtime restrictions
distribution	the official catalog and how TideMail installs plugins
compatibility	what API v1 promises

Small, tested example plugins are in examples/plugins/example/ and examples/plugins/analytics/ (a report). A GnuPG plugin that decrypts, verifies, signs and encrypts mail is in plugins/pgp in the plugins repository.

For TideMail contributors

The runtime is internal/plugin (discovery, manifest and protocol validation, process handling, permissions, annotation parsing, automatic events, query validation and the report round driver in query.go and report.go). Report queries execute in internal/pluginquery, which reads header columns through internal/db and shares conversation threading with the UI through internal/conversation. The UI side is in internal/ui (plugins.go, plugin_bulk.go for multi-message runs, plugin_report.go, plugin_annotations.go, tags.go for tag rendering, plugin_events.go, plugin_settings.go), and annotation storage is internal/db. See architecture.md. Tests in internal/plugin/docs_test.go check the examples in docs/plugins/ against the code, so keep them in step when the protocol changes.

---

Source in TideMail at 65f889c