Blue Knight VR Notes

MailMaven to Markdown AppleScript

Properties3
description—
tagsmyprojects/mailmaven
aliases—

4 min read

Why I Built This Script

The Reason

Managing email archives inside personal knowledge management systems like Obsidian can often be frustrating. Most standard email-to-markdown conversion scripts strip out HTML formatting, resulting in a single “wall of text” with broken line breaks, unformatted signatures, and lost context.

What I was trying to Achieve

I built AppleMail to Markdown (Obsidian Optimized) to bridge the gap between macOS Apple Mail and Obsidian. At the same time I was alpha/beta testing MailMaven a new mail client that has some unique workflows. Once the mail client had support for Applescript I started the conversion of the AppleMail to Markdown AppleScript to MailMaven.

I needed a reliable tool that could preserve the aesthetic integrity and visual layout of emails—including reply threads, clickable links, and metadata—while generating clean, Obsidian-ready Markdown notes.

Other Reasons for the Script

A lot of the reasons have to do with AI and I decided to create a separate page to show the work that can be done with this script.

Please see Markdown Mail Use for AI

What is the Goal of the Script

The main goal of this script is to provide a seamless, robust, and automated way to convert macOS Apple Mail messages directly into your Obsidian vault, or just to a directory.

Specifically, the script aims to:

  • Preserve Visual Structure: Ensure exported emails look as close as possible to their appearance in Apple Mail.
  • Integrate Native Obsidian Features: Automatically include YAML frontmatter, standardized tags, and clean file naming conventions for smooth vault organization.
  • Enable Direct Navigation: Create quick back-links using native Apple Mail message:// URIs so you can jump from your Obsidian note directly to the original email with a single click.
  • Support Workflow Automation: Work flexibly across manual execution, right-click context menus (Automator Quick Actions), or automated Apple Mail rules.

Functionality of the Script

The script includes several features designed to optimize your email archiving workflow:

Key Features

  • Layout Preservation: Utilizes a CSS-injected HTML wrapper with white-space: pre-wrap to prevent plain-text collapse and retain original email formatting, line breaks, and signatures.
  • Smart Linkification: Automatically detects plain (“naked”) URLs (e.g., google.com) and turns them into active, clickable links without corrupting existing HTML tags or email address domains.
  • Obsidian-Ready Frontmatter: Automatically formats metadata header blocks (YAML) containing clean titles, dates, and customizable nested tags (tagList).
  • Deep Linking (message://): Injects native macOS message:// URI headers into each note, allowing instant navigation back to the specific email in Apple Mail.
  • Thread Reply Subdivision: Optional setting (sub-divide-replies) that visually separates email thread replies with horizontal underscore dividers for improved legibility.
  • Sanitized File Names & Metadata: Automatically cleans titles and metadata keys by removing problematic characters (such as colons and semicolons) that cause issues across filesystem paths and YAML parsers.

Execution Modes

  1. Standalone AppleScript: Run directly from Script Editor on any selected emails in Apple Mail.
  2. Automator Quick Action: Integrated into the macOS right-click context menu (“Export to Markdown”).
  3. Apple Mail Rules: Trigger automatically when incoming emails match specified criteria (senders, keywords, or tags).

Future Plans for the Script

While I have recently transitioned to using MailMaven as my primary email client on macOS, this project remains actively maintained.

My ongoing plans for the script include:

  • Feature Backporting: Porting improvements, optimizations, and new features developed for the MailMaven AppleScript implementation back to this Apple Mail version.
  • Community-Driven Bug Fixes: Testing and fixing edge cases reported by the community regarding complex HTML structures or new macOS releases.
  • Community Ideas: There are discussion is available on the GitHub and any ideas will be considered for implementation.

Graph View

Backlinks