Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
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)