HeroMail

HERO-native mail control plane wrapping Stalwart as a runtime engine. Stalwart handles mail protocols and storage; HeroMail owns provisioning, administration, and the user experience.

Architecture

┌──────────────────────────────────────────────────────┐
│  hero_mail_ui                                        │
│  Web dashboard — Unix socket + HTTP proxy           │
│  Socket: ~/.hero/var/sockets/hero_mail_ui.sock      │
└──────────────────────┬───────────────────────────────┘
                       │ JSON-RPC /rpc proxy
┌──────────────────────▼───────────────────────────────┐
│  hero_mail_server                                    │
│  JSON-RPC 2.0 server — translates to Stalwart       │
│  Socket: ~/.hero/var/sockets/hero_mail_server.sock  │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│  Stalwart            (runtime engine)               │
│  SMTP / IMAP / JMAP — protocol handling + storage   │
└──────────────────────────────────────────────────────┘

Crates

Crate	Type	Description
hero_mail_sdk	library	Generated OpenRPC client with typed RPC methods
hero_mail_server	binary	JSON-RPC 2.0 server (OpenRPC spec: openrpc.json)
hero_mail_cli	binary	Command-line client for scripting and debugging
hero_mail_ui	binary	Admin web dashboard with RPC proxy pattern
hero_mail_examples	examples	Example programs and integration tests

RPC Methods

All methods use the mail. prefix over JSON-RPC 2.0.

Group	Methods
Domain	mail.domain.create, delete, list, update, get_dns_records
Account	mail.account.create, delete, disable, enable, set_password, set_quota, list, get
Group	mail.group.create, delete, add_member, remove_member, list
Mail	mail.mail.send, search, get, delete, move, mark_read, list_mailboxes, create_mailbox, delete_mailbox
Queue	mail.queue.list, retry, drop
System	mail.system.health, info, mail.stats.get, mail.logs.tail

Quick Start

# Build everything
make build

# Run server + UI (Ctrl-C to stop both)
make run

# Open dashboard
open http://127.0.0.1:3790

Make Targets

make build    Build all crates
make run      Run server + UI together
make server   Run the RPC server only
make ui       Run the UI only
make cli      Show CLI help
make stop     Kill running hero_mail processes
make check    Check all crates compile
make clean    Clean build artifacts

CLI Examples

# Domain management
cargo run -p hero_mail_cli -- domain create example.com
cargo run -p hero_mail_cli -- domain list

# Account management
cargo run -p hero_mail_cli -- account create user@example.com -p secret
cargo run -p hero_mail_cli -- account list

# Mail operations
cargo run -p hero_mail_cli -- mail send --from a@x.com --to b@x.com --subject Hi --body Hello
cargo run -p hero_mail_cli -- mail list --account user@example.com

# System
cargo run -p hero_mail_cli -- system health
cargo run -p hero_mail_cli -- queue list

SDK Usage

use hero_mail_sdk::sdk::HeroMailClient;

let client = HeroMailClient::new("http://localhost:3781/rpc");
// or Unix socket (recommended for production):
// let client = HeroMailClient::new("unix:///var/run/hero/sockets/hero_mail_server.sock");

let domains = client.domain_list(std::collections::HashMap::new()).await?;
let health = client.system_health(std::collections::HashMap::new()).await?;

Status

Server handlers currently return stub responses. Stalwart integration (config generation, API translation, binary management) is the next step.