# MailHub

Adopt this skill: https://proskills.md/skills/marketing/mailhub

Page: https://proskills.md/skills/marketing/mailhub
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .env.example
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/.env.example

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/.env.example

## File: .gitignore
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/.gitignore

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/.gitignore

## File: LICENSE
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/LICENSE

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/LICENSE

## File: PATHS.md
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/PATHS.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/PATHS.md

## File: PROVIDERS.md
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/PROVIDERS.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/PROVIDERS.md

## File: README.md
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/README.md

````text
# MailHub (OpenClaw Skill)

Unified multi-account mail/calendar/contacts connector.

## English

## 1) Overall

MailHub provides one CLI surface for mail, calendar, summary, and OpenClaw bridge workflows.

What it can do:

- Mail polling, triage, reply draft, send queue, auto-reply.
- Calendar view/add/delete/sync/remind/summary.
- Unified summary for mail + calendar by flexible datetime range.
- OpenClaw-oriented structured output for downstream agent UX.

TUI preview placeholder (replace with your real screenshot later):

![MailHub TUI Placeholder](./docs/images/tui-placeholder.svg)

If command usage is unclear:

```bash
mailhub --help
mailhub tui --help
mailhub mail --help
mailhub calendar --help
mailhub summary --help
mailhub openclaw --help
```

## 2) Run Modes

Two runtime modes are supported through the same command surface.

- `openclaw`: OpenClaw agent drives orchestration/reasoning.
- `standalone`: MailHub runs local scheduling and local agent bridge.

Execution path:

```mermaid
flowchart TD
    A["User / Trigger"] --> B["mailhub CLI entrypoint"]
    B --> C{"runtime mode"}
    C -->|"openclaw"| D["OpenClaw orchestrates"]
    C -->|"standalone"| E["local agent_bridge + standalone.models.json"]
    D --> F["MailHub pipelines"]
    E --> F
    F --> G["SQLCipher SQLite + KV + JSON output"]
```

### openclaw mode

Pros:

- Better natural-language orchestration in OpenClaw conversations.

Tradeoffs:

- Depends on OpenClaw runtime availability and routing.

### standalone mode

Pros:

- Suitable for daemon-style operation and scheduled processing.
- Can reuse OpenClaw-style runner config or fully custom models config.

Tradeoffs:

- Requires local runner/models setup and health checks.
- Loop path is checkpoint-driven (provider remote-id vs local stored state), not poll-window driven.
- MailHub no longer performs model heartbeat checks at loop start. Provider/model detection and fallback run only after a real inference call fails.
- New-mail pipeline in standalone loop: poll new messages -> one `classify_email` LLM call per message (summary+tag+reply suggestion) -> optional auto-draft/send.

### Daemon management

Foreground loop command:

```bash
mailhub mail loop --interval-seconds 60
```

`setup` can install service automatically in standalone mode:

- macOS: `launchd`
- Linux: `systemd --user`

Logs for daemon mode:

- Linux (`systemd --user`): `journalctl --user -u mailhub-loop.service -f`
- macOS (`launchd`): `tail -f ~/Library/Logs/mailhub-loop.log` (if redirected) or `log stream --predicate 'process CONTAINS "mailhub"'`

## 3) Primary Entrypoints

Configuration / Diagnostics:

- `mailhub wizard`: unified configuration wizard.
- `mailhub config`: first-run review/confirm gate.
- `mailhub doctor`: health checks (including standalone models link checks and dbkey backend evidence).
- `mailhub dbkey-setup`: SQLCipher dbkey bootstrap (detect/select/write/read/verify).

Account binding:

- `mailhub bind`: provider binding and account capability management.

Business entrypoints:

- `mailhub tui`: unified Textual TUI entrypoint.
- `mailhub mail`: mail workflow entrypoint.
- `mailhub calendar`: calendar workflow entrypoint.
- `mailhub summary`: summary workflow entrypoint.
- `mailhub openclaw`: OpenClaw bridge entrypoint.
- `mailhub test`: integration test entrypoint (interactive menu + direct case execution).

Interactive behavior:

- In standalone mode, `mailhub mail|calendar|summary|test` opens TUI menus when called without subcommands.
- In openclaw mode, use explicit subcommands for deterministic skill routing.
- Launcher behavior on Linux/systemd:
  - TTY interactive commands run through `systemd-run --pty` (low-latency terminal I/O).
  - Non-TTY calls keep `systemd-run --pipe` for script-friendly output capture.

## 4) Setup

Clone into skill directory and run setup wizard:

```bash
git clone https://github.com/Nonosword/openclaw-skill-mailhub ~/.openclaw/skills/mailhub && ~/.openclaw/skills/mailhub/setup --wizard --source env
```

Setup flow (current implementation):

1. Create venv + launcher, and initialize settings/models templates when missing.
2. Security strategy:
   - default (recommended): keep SQLCipher encryption, run dbkey bootstrap first (`mailhub dbkey-setup`)
   - fallback (unsafe): `setup --no-encryption` to skip dbkey and use plaintext SQLite
3. Detect dbkey methods and show only usable choices:
   - Keychain (`macOS Keychain` / `Linux Secret Service`)
   - systemd credentials (`CREDENTIALS_DIRECTORY/dbkey` or `MAILHUB_DBKEY_FILE`)
   - Local `dbkey.enc` fallback
4. After user selection, immediately verify:
   - read dbkey from selected backend
   - open SQLCipher DB
   - read/write health probe
5. If verification fails, rollback and provide actionable hints.
6. If dbkey backend changes, setup attempts DB rekey migration automatically.
7. Continue mode/setup flow: choose mode `openclaw` or `standalone`.
8. If standalone, choose model source:
   - `openclaw`: reuse OpenClaw-style runner preset, then provide OpenClaw JSON path, and auto-fill `standalone.models.json` with OpenClaw defaults (`agent.id`, `defaults.primary_model`, `providers` when empty).
   - `own`: generate default `standalone.models.json`, then fill it manually.
9. Optionally install and start background service (platform-aware).
10. `mailhub wizard` quick start section applies full config, reloads/restarts `mailhub-loop.service`, then exits wizard automatically.

Non-interactive example:

```bash
~/.openclaw/skills/mailhub/setup \
  --dir ~/.openclaw/skills/mailhub \
  --source env \
  --mode standalone \
  --model-source own \
  --standalone-models ~/.openclaw/state/mailhub/standalone.models.json \
  --install-service \
  --interval-seconds 60
```

Unsafe plaintext example:

```bash
~/.openclaw/skills/mailhub/setup --no-encryption
```

Rotate systemd dbkey explicitly (default setup reuses existing credential to avoid breaking old DB key):

```bash
~/.openclaw/skills/mailhub/setup --dbkey-backend systemd --rotate-systemd-dbkey
```

If setup doctor reports `file is not a database`, setup now auto-runs `mailhub db-rebuild --backup` once and reruns doctor.

### Doctor checks for standalone models link

`mailhub doctor` (and `--all`) checks:

- models file exists / JSON valid
- `runner.command` can be resolved/executed
- `openclaw_json_path` existence if referenced by runner args/template

### 4.2) Provider setup details

Provider-specific onboarding is moved to:

- [Provider Binding Guide](./PROVIDERS.md)

LLM prompt assets are centralized in `config/prompts/`:

- task prompts: `classify_email.md`, `draft_reply.md`, `summarize_bucket.md`
- write prompts: `write_auto_format.md`, `write_auto_optimize.md`
- contract definitions: `task_contracts.json`

## 5) Engineering Entry

### 5.1 `wizard` / `config` / `doctor` / `bind` / `dbkey-setup`

```bash
mailhub wizard
mailhub config
mailhub config --confirm
mailhub doctor
mailhub doctor --all
mailhub dbkey-setup
mailhub dbkey-setup --auto --non-interactive
mailhub db-rekey --old-backend local --new-backend systemd
mailhub db-rebuild --backup
mailhub bind
mailhub bind --list
mailhub bind --provider google --scopes gmail,calendar,contacts
```

### 5.2 `mail`

```bash
mailhub mail
mailhub mail run
mailhub mail run --confirm-config
mailhub mail loop --interval-seconds 60
mailhub mail inbox poll --since 15m
mailhub mail inbox ingest --date today
mailhub mail inbox list --date today --limit 20
mailhub mail inbox read --id "<mailhub_message_id>"
mailhub mail reply compose --message-id "<mailhub_message_id>" --mode auto
mailhub mail reply revise --id 2352 --mode optimize --content "<instructions>"
mailhub mail reply send --id 2352 --confirm-text "send" --message '{"Subject":"<subject>","to":"<to>","from":"<from>","context":"<context>"}'
mailhub send --id 2352 --confirm --message '{"Subject":"<subject>","to":"<to>","from":"<from>","context":"<context>"}'
mailhub send --list --confirm --bypass-message
```

Key logic:

- Increm
````

## File: SECURITY.md
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/SECURITY.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/SECURITY.md

## File: SKILL.md
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/SKILL.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/SKILL.md

## File: config
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/config

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/config

## File: docs
upstream: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/docs

Content is not inlined in the catalog. Read the upstream file: https://github.com/nonosword/openclaw-skill-mailhub/blob/HEAD/docs