Commands, arguments, and options for openship mail.
See the workflow guide for examples. Global flags such as --json go before the command; see global options.
openship mail
Self-hosted mail server (iRedMail) setup and admin [self-host]
openship mail [options] [command]| Subcommand | Purpose |
|---|---|
steps | List the mail setup steps |
status [serverId] | Show the setup progress for a mail server |
servers | List every server the mail stack is installed on |
scan <serverId> | Probe a server for an existing mail install (read-only) |
adopt <serverId> | Re-adopt an existing mail install whose orchestrator state was lost |
setup [options] <serverId> | Start or resume the mail setup wizard (streams over SSE) |
cancel | Cancel the mail setup currently running |
dns-ack <serverId> | Acknowledge that DNS records are published (releases the DKIM gate) |
ptr-ack <serverId> | Acknowledge that reverse DNS (PTR) is configured |
reset [options] <serverId> | Wipe the on-server setup state file (does NOT touch installed daemons) |
forget <serverId> | Stop managing a mail server (drops the DB row; leaves the stack + state intact) |
health [options] <serverId> | Show live status of every mail daemon, and whether mail is leaving the box |
logs [options] <serverId> <component> | Tail a mail component's journal (snapshot) |
postmaster | Manage the postmaster mailbox |
build [options] | Build the openship-mail engine image locally from a source checkout [dev] |
domain | Manage mail domains, their dependencies and DNS |
mailbox | Manage mailbox accounts and storage limits |
alias | Manage forwards and catch-all addresses |
certificate | Inspect and renew mail TLS through Openship's shared edge |
relay | Manage outbound SMTP delivery without exposing stored passwords |
backup | Manage mail backup policy; use openship backup for runs and restores |
inbound | Manage inbound-mail notification rules |
stats <server> | Read domain, account and storage totals |
dns-scan [options] <server> | Inspect mail DNS without changing records |
test-email [options] <server> | Send one delivery test to the specified recipient |
rotate-platform-mailbox [options] <server> | Rotate Openship's private delivery credential; never prints its password |
component [options] <server> <key> <action> | Control a managed mail component; inspect health to confirm recovery |
restart-all [options] <server> | Restart managed mail components; delivery may be briefly interrupted |
webmail | Deploy webmail through the normal app deployment workflow |
openship mail adopt
Re-adopt an existing mail install whose orchestrator state was lost
openship mail adopt [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Server ID to adopt |
openship mail backup
Manage mail backup policy; use openship backup for runs and restores
openship mail backup [options] [command]| Subcommand | Purpose |
|---|---|
get <server> | Read the current mail backup policy |
configure [options] <id> [file] | Set destination, schedule and included mail data; omitted retention is preserved |
runs <server> | Read the 50 most recent mail backup runs |
openship mail backup configure
Set destination, schedule and included mail data; omitted retention is preserved
openship mail backup configure [options] <id> [file]| Argument | Meaning |
|---|---|
id | Resource ID |
file | JSON input file, or - for stdin |
| Option | Meaning |
|---|---|
--schema | Print the accepted JSON schema without making a request |
openship mail backup get
Read the current mail backup policy
openship mail backup get [options] <server>openship mail backup runs
Read the 50 most recent mail backup runs
openship mail backup runs [options] <server>openship mail build
Build the openship-mail engine image locally from a source checkout [dev]
openship mail build [options]| Option | Meaning |
|---|---|
--context <dir> | Repo root containing apps/email/Dockerfile (default: checkout or cwd) |
--tag <ref> | Image ref to tag (default: the pinned openship-mail ref) |
openship mail cancel
Cancel the mail setup currently running
openship mail cancel [options]openship mail certificate
Inspect and renew mail TLS through Openship's shared edge
openship mail certificate [options] [command]| Subcommand | Purpose |
|---|---|
get <server> | get mail certificate status |
check <server> | check mail certificate status |
renew <server> | Renew a due certificate and reload SMTP/IMAP through the existing edge workflow |
auto-renew [options] <server> | Enable or disable scheduled renewal; monitoring remains available |
openship mail certificate auto-renew
Enable or disable scheduled renewal; monitoring remains available
openship mail certificate auto-renew [options] <server>| Option | Meaning |
|---|---|
--state <state> | Automatic renewal (choices: "on", "off") |
openship mail certificate check
check mail certificate status
openship mail certificate check [options] <server>openship mail certificate get
get mail certificate status
openship mail certificate get [options] <server>openship mail certificate renew
Renew a due certificate and reload SMTP/IMAP through the existing edge workflow
openship mail certificate renew [options] <server>openship mail component
Control a managed mail component; inspect health to confirm recovery
openship mail component [options] <server> <key> <action>| Argument | Meaning |
|---|---|
server | |
key | |
action | start, stop, or restart |
| Option | Meaning |
|---|---|
-y, --yes | Confirm component action |
openship mail dns-ack
Acknowledge that DNS records are published (releases the DKIM gate)
openship mail dns-ack [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Mail server ID |
openship mail dns-scan
Inspect mail DNS without changing records
openship mail dns-scan [options] <server>| Option | Meaning |
|---|---|
--domain <domain> | Domain to inspect |
openship mail forget
Stop managing a mail server (drops the DB row; leaves the stack + state intact)
openship mail forget [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Mail server ID |
openship mail health
Show live status of every mail daemon, and whether mail is leaving the box
openship mail health [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Mail server ID |
| Option | Meaning |
|---|---|
--refresh-reachability | Bypass the public reachability cache |
openship mail logs
Tail a mail component's journal (snapshot)
openship mail logs [options] <serverId> <component>| Argument | Meaning |
|---|---|
serverId | Mail server ID |
component | Component key (postfix|dovecot|amavis|clamav|iredapd|postgresql|…) |
| Option | Meaning |
|---|---|
-n, --lines <n> | Number of lines (max 1000) (default: 200) |
openship mail postmaster
Manage the postmaster mailbox
openship mail postmaster [options] [command]| Subcommand | Purpose |
|---|---|
set-password [options] <serverId> | Rotate the postmaster password |
openship mail postmaster set-password
Rotate the postmaster password
openship mail postmaster set-password [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Mail server ID |
| Option | Meaning |
|---|---|
--password <password> | New password (min 12 chars); prompted if omitted |
--password-file <file> | Password file, or - for stdin (keeps secrets out of process arguments) |
openship mail ptr-ack
Acknowledge that reverse DNS (PTR) is configured
openship mail ptr-ack [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Mail server ID |
openship mail relay
Manage outbound SMTP delivery without exposing stored passwords
openship mail relay [options] [command]| Subcommand | Purpose |
|---|---|
get <server> | Read masked relay settings |
configure [options] <id> [file] | Configure outbound SMTP; omit password to keep the saved one |
remove [options] <server> | Disable the relay and return to direct SMTP delivery |
openship mail relay configure
Configure outbound SMTP; omit password to keep the saved one
openship mail relay configure [options] <id> [file]| Argument | Meaning |
|---|---|
id | Resource ID |
file | JSON input file, or - for stdin |
| Option | Meaning |
|---|---|
--schema | Print the accepted JSON schema without making a request |
-y, --yes | Confirm this operation |
openship mail relay get
Read masked relay settings
openship mail relay get [options] <server>openship mail relay remove
Disable the relay and return to direct SMTP delivery
openship mail relay remove [options] <server>| Option | Meaning |
|---|---|
-y, --yes | Confirm direct delivery |
openship mail reset
Wipe the on-server setup state file (does NOT touch installed daemons)
openship mail reset [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Mail server ID |
| Option | Meaning |
|---|---|
-y, --yes | Skip the confirmation prompt |
openship mail restart-all
Restart managed mail components; delivery may be briefly interrupted
openship mail restart-all [options] <server>| Option | Meaning |
|---|---|
-y, --yes | Confirm restart |
openship mail rotate-platform-mailbox
Rotate Openship's private delivery credential; never prints its password
openship mail rotate-platform-mailbox [options] <server>| Option | Meaning |
|---|---|
-y, --yes | Confirm rotation |
openship mail scan
Probe a server for an existing mail install (read-only)
openship mail scan [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Server ID to scan |
openship mail servers
List every server the mail stack is installed on
openship mail servers [options]openship mail setup
Start or resume the mail setup wizard (streams over SSE)
openship mail setup [options] <serverId>| Argument | Meaning |
|---|---|
serverId | Server ID to install the mail stack on |
| Option | Meaning |
|---|---|
-d, --domain <domain> | Mail domain (e.g. example.com) |
--start-step <n> | Resume from a step returned by mail status |
--config <json> | iRedMail config overrides as a JSON object |
--config-file <file> | Setup config file, or - for stdin (recommended for passwords) |
openship mail stats
Read domain, account and storage totals
openship mail stats [options] <server>openship mail status
Show the setup progress for a mail server
openship mail status [options] [serverId]| Argument | Meaning |
|---|---|
serverId | Mail server ID (omit for the empty welcome shell) |
openship mail steps
List the mail setup steps
openship mail steps [options]openship mail test-email
Send one delivery test to the specified recipient
openship mail test-email [options] <server>| Option | Meaning |
|---|---|
--to <email> | Recipient for one real test message |
--from-domain <domain> | Sender's configured mail domain |
openship mail webmail
Deploy webmail through the normal app deployment workflow
openship mail webmail [options] [command]| Subcommand | Purpose |
|---|---|
targets <server> | List permitted targets for this mail server |
deploy [options] [file] | Deploy webmail and return IDs for openship deployment wait/logs |
deploy-external [options] [file] | Deploy webmail for an external IMAP/SMTP provider |
openship mail webmail deploy
Deploy webmail and return IDs for openship deployment wait/logs
openship mail webmail deploy [options] [file]| Argument | Meaning |
|---|---|
file | JSON input file, or - for stdin |
| Option | Meaning |
|---|---|
--schema | Print the accepted JSON schema without making a request |
-y, --yes | Confirm this operation |
openship mail webmail deploy-external
Deploy webmail for an external IMAP/SMTP provider
openship mail webmail deploy-external [options] [file]| Argument | Meaning |
|---|---|
file | JSON input file, or - for stdin |
| Option | Meaning |
|---|---|
--schema | Print the accepted JSON schema without making a request |
openship mail webmail targets
List permitted targets for this mail server
openship mail webmail targets [options] <server>