Mailstone

by Johannes Kaindl
5
4
3
2
1
Score: 32/100

Description

Obsidian plugin: mail as vault notes — a server-side folder decides what becomes a note; iMIP transport for calendar-notes.

Reviews

No reviews yet.

Stats

0
stars
961
downloads
0
forks
54
days
4
days
4
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
1
total issues
1
open issues
0
closed issues
290
commits

Latest Version

4 days ago

Changelog

Fixed

  • Front matter is only written when Obsidian can read it; notes whose front matter Obsidian shows as “Invalid properties” stay untouched (before, the plugin wrote into them without the property becoming visible). A block list with a blank line or a comment line inside no longer leaves the rest of the list behind as the value of the key before it when a mail note is updated (kit frontmatter-patch 0.94.0).

Changed

  • Shared building blocks updated to obsidian-kit 0.94.0 and code-kit 0.73.0. The loopback check for mail servers (::1 with or without brackets) and the link written for a related mail note now come from the kit.

README file from

Github

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.

License: AGPL-3.0 Docs: CC BY-SA 4.0 Release Platform

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 original (the .eml, or the message fetched from the server), 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

Settings → Community plugins → Browse → "Mailstone" → Install, then enable it. Updates arrive like for any Community plugin. The two ways below are alternatives.

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 -- --port <n> 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.
  1. Decide on the server which mail matters. Move it into your allowlist folder. The next sync — every few minutes, or Synchronise now in the sidebar — writes a note under Mail/<year>/ and the .eml under Mail/<year>/_eml/.
  1. Or work from the inbox tab. Open the sidebar with the ribbon icon or the command Mailstone: Open the sidebar panel, switch to Inbox, and use Move to vault on anything worth keeping. The message moves into the allowlist folder on the server, and the following sync writes the note.
  2. On a mail note, the command palette offers Re-render mail note from its original, Relink mail threads, Recompute threads, Stop following this thread, Follow this thread again, Extract an attachment from a mail note, Reply to a mail in the external mail client and Create a TaskNotes task. Only the ones that apply to the open note appear. Each one shows what it would change before it writes:

<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):

Setting What it does Default
IMAP / SMTP: Host, Port, TLS Implicit (usually 993/465) or STARTTLS (143/587) —
Username, Password The password lives in Obsidian's secret storage, never in data.json or the vault —
Identities Addresses you may send from; one is the default —
Folders: Inbox The folder the inbox tab lists INBOX
Folders: Allowlist The folder that decides what becomes a note Vault
Folders: Archive Where Archive moves a message Archive
Folders: Sent Where a sent copy is filed; empty turns the copy off Sent
Sync enabled / Sync interval (minutes) Automatic sync per account on / 5
Follow threads (copies mails on the server) Writes on your mail server. Each sync run copies mails of the last 60 days that belong to a thread you already have in your vault (In-Reply-To or References, inbox and sent folder) into the allowlist folder, at most 50 per run, so they become notes in the same run. The original stays where it is, and nothing is marked as read or deleted. Desktop only; a stopped thread is left out. Copies nothing while the Follow field is empty or unusable (a note under the switch says so). See How it works off

Global settings:

Setting What it does Default
Notes folder Where mail notes are created, in a subfolder per year Mail
Subfolder per year Turns the year subfolders off on
Save original as .eml Writes the original next to each new note. Off: no second copy of the personal data in the vault; Re-render and Extract an attachment then fetch the original from the server by Message-ID (desktop only, read-only), and Remove stored .eml files trashes the ones you already have. Mails without a Message-ID keep their .eml on
Thread field Front matter field that links every mail note to the earliest mail of its thread, the first mail to itself. Filled in when a note is created; Recompute threads fills it in for existing notes. Empty switches threads off empty
Follow field Front matter field on the first mail of a thread. false there means: stop following this thread. Stop following this thread and Follow this thread again set and remove it. A stopped thread is left out of Show follow-up mails and is not copied by Follow threads. Empty switches these two commands off mail_follow
Filename template Placeholders {date}, {time}, {slug}, {year} {date}-{time}-{slug}
Extra fields for new mail notes Fields written once into a note's front matter when it is first created, for example status: open none
Allowed note-creation values Values accepted for the fields written at creation mail
Plugins allowed to send Plugins that send through Mailstone without asking; revoke one to be asked again none
Status bar Shows the sync state in the status bar (desktop); turn it off if the bar gets too wide on
Open the panel at startup Opens the sidebar panel when Obsidian starts off
Debug log Writes the IMAP/SMTP dialogue to the developer console, passwords masked off
Language Interface language Automatic

Documentation

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.

The .eml is optional. If you would rather not keep a second copy of the message (and the personal data in it) in the vault, switch off Save original as .eml. Notes are written as before; when Re-render or Extract an attachment then needs the original, Mailstone fetches it from the server by Message-ID, read-only and without marking anything as read, searching the note's folder, then the allowlist and archive folders. That works on the desktop only, and it needs the message to still be on the server; if it is not, the command says which folders it searched. Remove stored .eml files moves the ones you already have to the trash (after a preview, never touching a note).

Threads are links, not folders. With a Thread field set (say vorgang), every new note gets a link to the earliest mail of its thread, found through In-Reply-To and References. A new note takes the value of the mail it replies to, so nothing is regrouped at sync time; Recompute threads regroups the whole vault when you want it (after a preview, and it changes nothing but that one field). Because the value is an ordinary link, a Base can group by it.

Follow-up mails. Show follow-up mails (desktop, command palette) reads the inbox and the sent folder of every account, read-only (EXAMINE, BODY.PEEK, no \Seen), and lists, grouped by thread, the mails of the last 60 days that belong to a thread in your vault through In-Reply-To or References but have no note yet. It shows what is there and writes nothing. Stop following this thread and Follow this thread again mark the first mail of a thread with false in the Follow field (after a preview, front matter only); a stopped thread is left out of that list and of the copying below.

Following threads writes on your mail server (opt-in, off by default). With Follow threads switched on for an account, each sync run first finds those follow-up mails, and then copies them (UID COPY) from the inbox or sent folder into the allowlist folder on the server, at most 50 per run, oldest first. The normal sync that follows turns the copies into notes in the same run. Why a copy: the allowlist folder stays the one source of truth for what becomes a note, and the mail stays visible where it was. What you should know before you switch it on: the allowlist folder grows by those copies (the mails exist twice on the server and count against your quota); a copy keeps the flags of the original, so an unread mail is unread in the allowlist folder too, and anything else that watches that folder (another tool, a mail rule) sees the copies as new mail; moving a copy out of the folder detaches its note as usual. A mail is never copied twice (Mailstone checks the allowlist folder for its Message-ID first), and a mail without a usable Message-ID is not copied at all. Mailstone reads with EXAMINE and BODY.PEEK as before and opens the writing connection only when there is something to copy; it never marks anything as read, moves or deletes. Failed copies (quota, rights, a folder that does not exist) count as errors in the run and do not stop it. Nothing is copied either while the Follow field is empty or unusable: without it Mailstone could not tell which threads you stopped, so the step is skipped and the sync itself runs as usual. Turn the switch off and nothing is copied any more; copies already made stay.

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, UID MOVE or UID COPY; those live on a separate session used only by the inbox actions and by the optional Follow threads step. 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

Copyright © 2026 Johannes Kaindl.