Mailstone

Mailstone

🇬🇧 English · 🇩🇪 Deutsch

Mailstone turns a mail folder on your server into notes in your vault — the server decides what becomes a note, and reading never marks a message as read.

Triage stays where your mail already lives: move a message into one designated IMAP folder — from your phone, from webmail, from a mail rule — and the next sync writes it into the vault as a Markdown note, with the original .eml beside it. Sending uses the same account over SMTP, and the plugin delivers iMIP calendar invitations on behalf of the sister plugin calendar-notes.

Features

• Mail as notes. A server-side folder decides what becomes a note. The Message-ID is the identity, and the original .eml stays next to the note, so everything derived from it can be rebuilt.
• A panel in the right sidebar. Per account: what the last run did, when the next one is due, the counters that are not zero, the error in plain words — and a button to synchronise now, for one account or all of them. The last run survives a restart.
• An inbox tab. The last 100 messages of your inbox, with a tick for everything that is already a note. Three actions per row: Move to vault and Archive (both server-side, both after a confirmation) and — once TaskNotes is installed — Create task.
• Commands on a mail note. Re-render from the .eml, relink threads, extract an attachment, reply in your external mail client, create a TaskNotes task. Each shows a preview before it writes.
• Import without a server. Import .eml files from a vault folder turns .eml files you already have into notes — no account needed.
• Sending. SMTP through the same account, including iMIP invitations for calendar-notes. Other plugins can send through Mailstone too, after you confirm each one once.
• Reading never marks anything as read. Listing, previewing and syncing use EXAMINE and BODY.PEEK; moving a message carries its flags along. Another tool that keys off "unread" is not disturbed.
• Mobile: read what is already synced. Synchronised notes are ordinary Markdown notes on mobile. Sync, sending and the inbox tab need a network layer mobile Obsidian does not provide and stay off there.

Requirements

• Obsidian 1.13.0 or newer. Desktop for everything; mobile only reads notes that a desktop already synchronised.
• An IMAP/SMTP account you can reach with an app password. Providers that require OAuth (Gmail with 2FA, Microsoft 365) are not supported — there is no OAuth flow.
• A folder on the mail server that acts as the allowlist (default name Vault), and a second one for the archive. Anything you file in the allowlist folder becomes a note; nothing else is touched.
• TLS is not optional. Certificate checking cannot be turned off, and plaintext authentication without TLS is refused.

Install

Community Plugins

Listing in the Community Plugins directory is pending review. Once it is through: Settings → Community plugins → Browse → "Mailstone". Until then use one of the ways below.

AnySource Sideloader

AnySource Sideloader installs and updates plugins from any git forge. Subscribe to this catalog once:

https://git.jkaindl.de/jkaindl/obsidian-catalog/raw/branch/main/catalog.json

Mailstone then appears in the sideloader's plugin list and updates like any other plugin, every download checksum-verified.

Manual

Download main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/mailstone/, then enable the plugin in Settings → Community plugins. Updates then have to be repeated by hand.

BRAT (beta)

Add johannes-kaindl/mailstone in BRAT.

From source

git clone https://git.jkaindl.de/jkaindl/mailstone
cd mailstone && npm install && npm run build
# main.js manifest.json styles.css → <vault>/.obsidian/plugins/mailstone/

npm run gate runs the full check suite (lint, type checks, unit and integration tests, purity check, build). npm run smoke:e2e is a maintainer-only check against a running Obsidian with TaskNotes installed; it is deliberately not part of gate.

Usage

1. Set up an account. Settings → Mailstone → Add account: IMAP and SMTP host, port and TLS mode, username, an app-specific password, at least one identity, and the folder names as your IMAP server shows them. Test SMTP connection checks host, TLS and login without sending anything.

<img src="https://raw.githubusercontent.com/johannes-kaindl/mailstone/main/docs/images/relink-preview.png" width="820" alt="The "Review before writing" dialog of the Relink mail threads command: one note gets a wikilink in in_reply_to, shown as Before and After, with Cancel and Apply.">

Configuration

Click the preview for the full-size image

Settings → Mailstone. Per account (Add account / Edit):

Global settings:

Documentation

• Documentation index
• Getting started — from installation to your first mail note
• Troubleshooting — the error messages, what causes them, what to do

How it works

The server decides, not the plugin. A folder on the mail server is the allowlist. Sync reads it, and every message in it becomes a note — no rules engine, no filters in the plugin.

The Message-ID is the identity. It survives re-downloads, folder moves and renamed files. The .eml next to each note is the fidelity surface: front matter, rendered body and attachments can be rebuilt from it, so a formatting change never costs you data.

Notes are merged, not overwritten. Your own text lives outside a marked zone (%% mailstone:begin %% … %% mailstone:end %%) and is compared by hash before any write. If you edited the managed zone, the write is refused rather than silently applied. Mailstone never deletes a note: a message that leaves the folder is marked detached, and putting it back reattaches it.

Two kinds of IMAP session, enforced by the compiler. The read path cannot call SELECT or UID MOVE; those live on a separate session used only by the inbox actions. That is why "reading never marks as read" is a property of the type system, not a rule someone has to remember. Architecture and conventions are in AGENTS.md.

Contributing

Issues and pull requests on GitHub; the canonical repository is on git.jkaindl.de. Test-driven (npm test, full check with npm run gate); larger features go through brainstorm → spec → plan → TDD. See AGENTS.md.

License

• Code: AGPL-3.0-or-later (LICENSE; dual-license option in LICENSING.md).
• Docs/Text: CC BY-SA 4.0 (LICENSE-DOCS).

Copyright © 2026 Johannes Kaindl.