himalaya-kit

himalaya-kit is a Python toolkit that complements the himalaya mail CLI for automation and AI-assisted workflows. It combines himalaya primitives into safer multi-step workflows for composing, sending, searching, batch-exporting, and optionally organizing mail.

Project status: Alpha. The core workflows are usable, but command output and public interfaces may still evolve across 0.x releases.

Why this project exists

himalaya already provides a solid foundation for mail access and folder management. himalaya-kit is designed to fill the gaps that often appear in scripted or agent-driven workflows by offering a small, reusable layer on top of himalaya rather than replacing it.

Features

Optional workflows:

Installation

pip install himalaya-kit

Or install from source:

git clone https://github.com/xiaolinstar/himalaya-kit.git
cd himalaya-kit
pip install -e .

Quick start

# Check how himalaya-kit is connected (does not authenticate to mail servers)
himalaya-kit status
himalaya-kit status --backend native --json

# Send a message
himalaya-kit send -t "张三 <zhangsan@example.com>" -s "测试" -b "你好"

# Send Markdown mail
echo "# 报告" | himalaya-kit send -t user@example.com -s "周报" --markdown

# Reply to an existing message
himalaya-kit reply 12345 -b "收到，谢谢"

# Forward a message
himalaya-kit forward 12345 user@example.com --note "请查收"

# Search mail by sender
himalaya-kit search "Alice"

# Archive mail from the inbox
himalaya-kit archive --days 7

# Preview archive actions without moving mail
himalaya-kit archive --dry-run

# Preview a safe batch export (zero local writes and no server changes)
himalaya-kit export --before 2025-01-01 --dry-run

# Export one full message with native himalaya
himalaya message export --full -d message.eml 12345

himalaya vs himalaya-kit

Use himalaya directly when one native command safely completes the task. Use himalaya-kit when the task needs batching, validation, durable state, recovery, or coordination across multiple himalaya commands.

archive copies messages into priority folders and leaves the originals in place. yearly-archive is retained as a destructive compatibility workflow: after verified local export and index persistence, it marks server copies as deleted. Always run destructive workflows with --dry-run first.

Safe batch export

# Strictly before the given date; defaults to INBOX
himalaya-kit export --before 2025-01-01 --dry-run

# Export a calendar year from multiple folders
himalaya-kit export --year 2025 \
  --folder INBOX --folder Sent \
  --output ~/email-archive/work

# Export an open/closed date range using strict boundaries
himalaya-kit export --after 2024-01-01 --before 2025-01-01

# Machine-readable plan for an Agent
himalaya-kit export --year 2025 --dry-run --json

# Destructive option: only delete after verified export and durable index save
himalaya-kit export --before 2025-01-01 --delete-after-export

Exports use himalaya's native envelope list and message export commands. himalaya-kit adds atomic file writes, basic .eml validation, collision-resistant names, an atomic archive-index.json, and repeat-run recovery. --dry-run does not create the output directory or modify server state.

Human-facing runs emit stable line-oriented logs as folders are scanned and messages complete, followed by a summary. --json suppresses those text logs and writes one complete JSON result to stdout for Agents and scripts. Dynamic terminal progress bars are intentionally not used.

Requirements

• Python 3.10+
• The himalaya CLI installed and configured
• A himalaya config file at ~/.config/himalaya/config.toml

Internationalization (i18n)

himalaya-kit supports Chinese (default) and English interfaces. You can switch languages in three ways:

1. Command-line argument

himalaya-kit --lang en send --help
himalaya-kit --lang zh send --help

2. Environment variable

export HIMALAYA_KIT_LANG=en
himalaya-kit send --help

3. Config file

[himalaya_kit]
lang = "en_US"

Supported language codes:

• zh_CN or zh - Chinese (default)
• en_US or en - English

Configuration

himalaya-kit reuses the existing himalaya account configuration and does not require a separate mail setup. A typical configuration looks like this:

[accounts.work]
default = true
email = "yourname@company.com"
display-name = "Your Name"
# ... SMTP/IMAP settings

Optional extensions can be added under the [himalaya_kit] section:

[himalaya_kit]
backup-root = "~/email-archive"

my-email = "yourname@company.com"
priority-contacts = ["boss@company.com"]
system-accounts = ["noreply@company.com"]
internal-domains = ["company.com"]
timezone = "Asia/Shanghai"

notification-keywords = ["notification", "alert", "通知", "提醒"]

priority-folders = [
    "Priority-1-Urgent",
    "Priority-2-Internal",
    "Priority-3-External",
    "Priority-4-CC",
    "Priority-5-Notifications",
]

[himalaya_kit.contacts]
provider = "json"   # none | json | ai-todo
file = "~/.config/himalaya/contacts.json"

See examples/config.example.toml and examples/contacts.example.json for full examples.

Contacts: himalaya has no built-in address book. Use a local JSON file (default provider when configured) or optionally plug in ai-todo as an external contact source. Contacts with "tags": ["priority"] are merged into high-priority classification alongside priority-contacts.

Backward compatibility: leader-emails is still read and merged into priority-contacts.

Environment variables:

Python API

himalaya-kit 0.3 introduces a stable, Python-first SDK. The CLI calls the same client API, while himalaya command execution is isolated behind a replaceable backend:

from datetime import date

from himalaya_kit import ExportSelection, HimalayaKit, SendRequest

kit = HimalayaKit(account="work")

# Local integration only: no IMAP/SMTP authentication.
print(kit.status().to_dict())

# A dry run builds the complete message without resolving SMTP credentials.
preview = kit.send(
    SendRequest(
        to="reader@example.com",
        subject="Weekly update",
        body="Hello from Python",
    ),
    dry_run=True,
)
print(preview.preview)

# Structured result suitable for scripts and Agents.
result = kit.export(
    ExportSelection(before=date(2025, 1, 1)),
    dry_run=True,
)
print(result.to_dict())

The default HimalayaCliBackend keeps full compatibility with himalaya. The optional NativePythonBackend uses Python's standard-library IMAP/SMTP clients while continuing to read the same himalaya account configuration:

from himalaya_kit import HimalayaKit, NativePythonBackend

kit = HimalayaKit(account="work", backend=NativePythonBackend())

For CLI comparison and gradual migration, add --backend native to status or export. The native backend initially covers the safe export workflow; reply, forward, search, and optional organization workflows continue to use himalaya primitives.

Development

Run the test suite with:

pytest -q

License

Apache License 2.0