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        (port 3790)                    │
│  Web dashboard — proxies JSON-RPC to server         │
└──────────────────────┬──────────────────────────────┘
                       │ POST /rpc
┌──────────────────────▼──────────────────────────────┐
│  hero_mail_server    (port 3791)                    │
│  JSON-RPC 2.0 server — translates to Stalwart API   │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│  Stalwart            (runtime engine)               │
│  SMTP / IMAP / JMAP — protocol handling + storage   │
└─────────────────────────────────────────────────────┘

Crates

Crate	Type	Description
hero_mail	library	SDK/client with typed RPC methods, HTTP + Unix socket support
hero_mail_server	binary	Axum JSON-RPC server dispatching mail.* methods
hero_mail_cli	binary	Command-line client for scripting and debugging
hero_mail_ui	binary	Bootstrap web dashboard with RPC proxy pattern

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::HeroMailClient;

let client = HeroMailClient::new("http://localhost:3791/rpc");
// or Unix socket:
// let client = HeroMailClient::new("unix:///var/run/hero_mail.sock");

let domains = client.domain_list().await?;
let health = client.system_health().await?;
client.mail_send("a@x.com", &["b@x.com"], "Subject", "Body").await?;

Status

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