obsidIMAP

IMAP to Obsidian email importer - automatically imports matching emails as markdown files into your Obsidian vault.

Features

• Searches specified IMAP folders for emails containing keywords
• Imports emails as formatted markdown files
• Preserves subject, sender, date, and body content
• Moves processed emails to a separate folder (doesn't delete)
• Secure password prompt (no credentials stored in code)

Installation

This project uses uv for Python dependency management.

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# The project has no external dependencies - just use uv run
uv run imap_to_obsidian.py

Initial Setup

First time using obsidIMAP? Run the interactive setup wizard:

uv run setup_config.py

The wizard will guide you through:

1. Select your email provider (Gmail, Outlook, Yahoo, or custom)
2. Enter your credentials (password is hidden for security)
3. Configure keywords to match emails you want to import
4. Set folder paths for imported emails and processed messages

Example setup session:

STEP 1: Select your email provider
1. Gmail
2. Outlook/Office365
3. Yahoo Mail
4. Custom/Other

Select provider (1-4): 1

💡 Requires App Password: https://support.google.com/accounts/answer/185833

Custom output path:

# Create a specific config file
uv run setup_config.py --config Email_import_config_work.md

# Preview what would be generated (dry run)
uv run setup_config.py --dry-run

After setup, you can immediately run the importer with your new configuration!

Configuration

Edit Email_import_config.md in your Obsidian vault:

---
# Email Server Settings
email_user: "your_email@example.com"
email_password: "your_app_password_here"
imap_server: "imap.gmail.com"
imap_port: 993

# Search these server folders
target_folders:
  - "INBOX"

# Filter Rules (Matches ANY of these)
keywords:
  - "Obsidian"
  - "Receipt"
  - "Project Alpha"

# Blacklist - excludes these even if they match keywords
blacklist:
  - "newsletter"
  - "unsubscribe"
  - "spam"

# Output settings
import_folder: "Inbox/Emails"
daily_note_folder: "_daily"

# Where to move emails after import
processed_folder: "INBOX/Obsidian_Imports"

# Dry run mode - test without creating files or moving emails
dry_run: true
---

Multiple Profiles

You can create multiple config files for different email accounts or filtering rules:

# Default profile
uv run imap_to_obsidian.py

# Work profile
uv run imap_to_obsidian.py -c Email_import_config_work.md

# Personal profile
uv run imap_to_obsidian.py --config ~/ObsidiVault/Email_import_personal.md

Usage

Run the script:

uv run imap_to_obsidian.py

The script will:

1. Connect to your IMAP server
2. Search configured folders for matching keywords
3. Create markdown files in your Obsidian vault (unless in dry-run mode)
4. Move processed emails to the processed folder (unless in dry-run mode)

Dry Run Mode

Always test with dry-run mode first! Set dry_run: true in your config to:

• See what emails would be matched
• Preview the filenames that would be created
• No files are written, no emails are moved

Once you're satisfied with the results, set dry_run: false to run for real.

Cron Jobs

Set up automated imports for multiple profiles:

# Edit crontab
crontab -e

# Default profile at 11 PM
0 23 * * * /usr/bin/uv run imap_to_obsidian.py >> /home/nico/ObsidiMax/.obsidimap_cron.log 2>&1

# Work profile at 8 AM
0 8 * * * /usr/bin/uv run imap_to_obsidian.py -c Email_import_config_work.md >> /home/nico/ObsidiMax/.obsidimap_cron.log 2>&1

Project Structure

obsidIMAP/
├── imap_to_obsidian.py    # Main script
├── pyproject.toml         # uv configuration
└── README.md              # This file

Config files live in your Obsidian vault:

• Email_import_config.md (default)
• Email_import_config_work.md (optional, for work email)
• Email_import_config_personal.md (optional, for personal email)