HEE-MAIL(8) HEE Tools HEE-MAIL(8)
NAME
hee-mail - mailboxes, aliases and master access on the fleet's mail
exchanger
SYNOPSIS
hee mail list
hee mail add NAME[@DOMAIN] -recipients KEYID[,KEYID...]
hee mail passwd NAME[@DOMAIN] -recipients KEYID[,KEYID...]
hee mail alias ADDR TARGET
hee mail unalias ADDR
hee mail master NAME[@DOMAIN]
hee mail unmaster NAME[@DOMAIN]
hee mail record [-write]
hee mail check [DOMAIN]
hee mail domain list | add DOMAIN | handoff DOMAIN
hee mail login NAME[@DOMAIN]
hee mail relay show | set -label L -host H [-port P] -user U -cred ACCOUNT | clear
hee mail send -from ADDR -to ADDR[,ADDR] -subject S [-body FILE] [options]
hee mail help
DESCRIPTION
One mailbox is three things that must agree: a row in the mail host's
virtual table (where the address goes), a credential in two files on that
host (smtpd for submission, dovecot for IMAP), and a sealed password
someone can actually open. This tool keeps them in step; doing it by hand
is how a password works on 587 and not on 993.
The mail host is named by a package directory -- the fleet-ops
hosts/<mx>/ tree that carries node.conf (its address), known_hosts
(its pinned key) and tables/ (its domains and virtuals). Default:
~/git/fleet-ops/hosts/mx1-tcosagent-com, or $HEE_MAIL_PKG.
add generates a password with hee-pwgen, seals it to -recipients as
mail-<name> in the package repo's .hee/secrets, hashes it ON the mail
host with `smtpctl encrypt`, writes that hash to both credential files,
and creates the Maildir owned by vmail. The plaintext is held in one
shell variable, handed to gpg and to ssh on stdin, and never printed,
never in argv, never in a file. passwd is the same thing for an address
that already exists -- a rotation.
Seal to every key that has a real reason to open it: the mailbox owner's
personal key AND the per-host key of each machine they read mail from
(HEE_POLICY ยง24). A password sealed only to a key that lives on another
machine is a password nobody can use where they are.
master makes an account a dovecot master user: it then opens any mailbox
as "<mailbox>*<master>" with its own password, and dovecot logs every
such login. No password is generated or changed, and nothing is copied.
This is how an operator reads the fleet's mail without holding anyone
else's credential.
record renders the mailbox list as YAML under the package's repo
(mail/accounts.<domain>.yaml). It holds addresses, kinds and recipients
-- never a password or a hash. inv.lab already syncs fleet-ops, so the
record is how mail identities reach the inventory rather than a second
API to keep alive.
domain add takes a zone this exchanger should receive for: a line in
tables/domains, a catch-all row in tables/virtuals, and a records file
under the repo's dns/ carrying MX, SPF, DKIM and DMARC for it. Nothing is
published -- bin/dns-records.sh does that, per zone, and bin/push.sh
deploys the tables. One shared DKIM key signs every domain, because
filter-dkimsign takes one key and many domains.
domain handoff is for selling. A domain is worth more with its mail
working, and a buyer must not receive the key that signs everyone else's:
it prints the zone's records, its addresses, and the exact steps to cut it
over -- starting with a FRESH per-domain DKIM key, because the shared one
can never leave this fleet. Operator, 2026-09-19: "once we (if we) sell a
domain and it's mail it should be fully configured to hand off. we build
businesses to sell, that is our deal."
login is for the human at the keyboard: it opens that mailbox's sealed
password, puts it on the clipboard, and prints the server settings to type
into a mail client. The password is never printed, never written to a
file, and never passed on a command line -- it goes from gpg into the
clipboard tool's stdin and nowhere else. Clear the clipboard afterwards;
the tool says how.
relay is the exchanger's own way out. A cloud host usually cannot reach
port 25, 465 or 587 outbound (DigitalOcean blocks all three on every
droplet), so mail for a foreign domain queues forever unless it is handed
to a provider on an alternate submission port -- 2525 is the one the
industry settled on, and it is open where the others are not.
relay set writes two things: relay.conf in the host package (the label,
host and port -- public, committed) and one row in the box's relaycreds
table (the password, opened from a sealed credential and pushed over ssh,
never printed). Seal the provider's key first, at a terminal:
hee cred -seal relay-sendgrid -recipients <keyid>,<keyid>
hee mail relay set -label sendgrid -host smtp.sendgrid.net \
-port 2525 -user apikey -cred relay-sendgrid
Then deploy: the outbound action is rebuilt from relay.conf on the next
bin/push.sh, and falls back to a direct relay if the row is missing --
so a half-done change queues mail rather than losing it.
send submits ONE message, authenticated, with the certificate verified.
It is here rather than in each caller because three separate things had
started to grow their own submission code -- the exchanger's own
flow-check.py, CI, and the store service's order notice -- and every copy
is a fresh chance to get TLS verification or credential handling subtly
wrong. The body is read from stdin and the password from MAIL_PASSWORD,
so neither is ever visible in `ps`:
hee cred -pass mail-store -exec sh -c \
'MAIL_PASSWORD="$HEE_CRED_PASS" hee mail send \
-from store@tcos.app -to orders@tcos.app -subject "order 260921-001"' \
< notice.txt
Port 587 (STARTTLS) is the default and 465 (implicit TLS) works the same
way. Port 25 is REFUSED: it is the port between exchangers, it carries no
credential, and a fleet host reaching for it is nearly always a mistake
that would deliver by accident and then be filed as spam. -dry-run prints
the exact message including the body -- which is the one place someone is
checking what a customer would actually receive -- and opens no socket.
OPTIONS
-recipients IDS with add/passwd: GPG key ids or emails, comma separated
-pkg DIR the mail host package (default: $HEE_MAIL_PKG, else
~/git/fleet-ops/hosts/mx1-tcosagent-com)
-target root@HOST override the address in the package's node.conf
-domain DOMAIN default domain for a bare NAME (default: tcosagent.com)
-write with record: write the file (default prints it)
-label L with relay set: the smarthost's label in the creds table
-host H with relay set: the provider's SMTP host; with send: the
exchanger to submit to (default mx1.tcosagent.com)
-port P with relay set: its port (default 2525); with send: 587
STARTTLS (default) or 465 implicit TLS. 25 is refused
-user U with relay set: the username the provider expects; with
send: the submission username (default: the -from address)
-cred ACCOUNT with relay set: the sealed credential holding the password
-from ADDR with send: the envelope and header sender. Required
-to ADDR[,ADDR] with send: recipients, comma separated. Required
-subject S with send: the subject. Required
-body FILE with send: the body (default: stdin, and `-` means stdin)
-reply-to ADDR with send: a Reply-To header
-name NAME with send: a display name for the sender
-header NAME=V with send: one extra header, repeatable. A value with a
newline is refused -- that is header injection
-json with send: print the envelope as JSON instead of a line
-dry-run with add/passwd: run every check, change nothing.
With send: print the whole message, open no socket
ENVIRONMENT
MAIL_PASSWORD with send: the submission password. Never an argument --
an argument is visible in `ps` to every user on the box
HEE_MAIL_HOST with send: default for -host
HEE_MAIL_PORT with send: default for -port
HEE_MAIL_PKG default for -pkg
HEE_MAIL_DOMAIN default for -domain
EXIT STATUS
Nagios plugin convention.
0 OK 1 WARNING 2 CRITICAL 3 UNKNOWN (usage)
EXAMPLES
$ hee mail help # ci
$ hee mail domain add hee.run
$ hee mail add spencer@hee.run -recipients 18602F28834DBB05
$ hee mail domain handoff hee.run
$ hee mail login spencer
$ hee mail relay show
$ hee mail list
$ hee mail add spencer -recipients 18602F28834DBB05,01C9F82A7582A4DC
$ hee mail alias postmaster@tcosagent.com spencer@tcosagent.com
$ hee mail master spencer
$ hee mail record -write
$ echo hi | hee mail send -from ci@tcosagent.com -to spencer@tcosagent.com -subject test -dry-run
HEE-MAIL(8)