# mail
URL: https://synquic.tech/docs/cli/reference/mail.md

Commands, arguments, and options for synq mail.

See the [workflow guide](/docs/cli/self-host) for examples. Global flags such as `--json` go before the command; see [global options](/docs/cli/reference#global-options).

## synq mail

Self-hosted mail server (iRedMail) setup and admin [self-host]

```text
synq mail [options] [command]
```

| Subcommand | Purpose |
| --- | --- |
| [`steps`](/docs/cli/reference/mail#synq-mail-steps) | List the mail setup steps |
| [`status [serverId]`](/docs/cli/reference/mail#synq-mail-status) | Show the setup progress for a mail server |
| [`servers`](/docs/cli/reference/mail#synq-mail-servers) | List every server the mail stack is installed on |
| [`scan <serverId>`](/docs/cli/reference/mail#synq-mail-scan) | Probe a server for an existing mail install (read-only) |
| [`adopt <serverId>`](/docs/cli/reference/mail#synq-mail-adopt) | Re-adopt an existing mail install whose orchestrator state was lost |
| [`setup [options] <serverId>`](/docs/cli/reference/mail#synq-mail-setup) | Start or resume the mail setup wizard (streams over SSE) |
| [`cancel`](/docs/cli/reference/mail#synq-mail-cancel) | Cancel the mail setup currently running |
| [`dns-ack <serverId>`](/docs/cli/reference/mail#synq-mail-dns-ack) | Acknowledge that DNS records are published (releases the DKIM gate) |
| [`ptr-ack <serverId>`](/docs/cli/reference/mail#synq-mail-ptr-ack) | Acknowledge that reverse DNS (PTR) is configured |
| [`reset [options] <serverId>`](/docs/cli/reference/mail#synq-mail-reset) | Wipe the on-server setup state file (does NOT touch installed daemons) |
| [`forget <serverId>`](/docs/cli/reference/mail#synq-mail-forget) | Stop managing a mail server (drops the DB row; leaves the stack + state intact) |
| [`health <serverId>`](/docs/cli/reference/mail#synq-mail-health) | Show live status of every mail daemon, and whether mail is leaving the box |
| [`logs [options] <serverId> <component>`](/docs/cli/reference/mail#synq-mail-logs) | Tail a mail component's journal (snapshot) |
| [`postmaster`](/docs/cli/reference/mail#synq-mail-postmaster) | Manage the postmaster mailbox |
| [`build [options]`](/docs/cli/reference/mail#synq-mail-build) | Build the synq-mail engine image locally from a source checkout [dev] |

## synq mail adopt

Re-adopt an existing mail install whose orchestrator state was lost

```text
synq mail adopt [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Server ID to adopt |

## synq mail build

Build the synq-mail engine image locally from a source checkout [dev]

```text
synq 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 synq-mail ref) |

## synq mail cancel

Cancel the mail setup currently running

```text
synq mail cancel [options]
```

## synq mail dns-ack

Acknowledge that DNS records are published (releases the DKIM gate)

```text
synq mail dns-ack [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Mail server ID |

## synq mail forget

Stop managing a mail server (drops the DB row; leaves the stack + state intact)

```text
synq mail forget [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Mail server ID |

## synq mail health

Show live status of every mail daemon, and whether mail is leaving the box

```text
synq mail health [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Mail server ID |

## synq mail logs

Tail a mail component's journal (snapshot)

```text
synq 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") |

## synq mail postmaster

Manage the postmaster mailbox

```text
synq mail postmaster [options] [command]
```

| Subcommand | Purpose |
| --- | --- |
| [`set-password [options] <serverId>`](/docs/cli/reference/mail#synq-mail-postmaster-set-password) | Rotate the postmaster password |

## synq mail postmaster set-password

Rotate the postmaster password

```text
synq mail postmaster set-password [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Mail server ID |

| Option | Meaning |
| --- | --- |
| `--password <password>` | New password (min 12 chars); prompted if omitted |

## synq mail ptr-ack

Acknowledge that reverse DNS (PTR) is configured

```text
synq mail ptr-ack [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Mail server ID |

## synq mail reset

Wipe the on-server setup state file (does NOT touch installed daemons)

```text
synq mail reset [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Mail server ID |

| Option | Meaning |
| --- | --- |
| `-y, --yes` | Skip the confirmation prompt |

## synq mail scan

Probe a server for an existing mail install (read-only)

```text
synq mail scan [options] <serverId>
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Server ID to scan |

## synq mail servers

List every server the mail stack is installed on

```text
synq mail servers [options]
```

## synq mail setup

Start or resume the mail setup wizard (streams over SSE)

```text
synq 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 specific step (1-13) |
| `--config <json>` | iRedMail config overrides as a JSON object |

## synq mail status

Show the setup progress for a mail server

```text
synq mail status [options] [serverId]
```

| Argument | Meaning |
| --- | --- |
| `serverId` | Mail server ID (omit for the empty welcome shell) |

## synq mail steps

List the mail setup steps

```text
synq mail steps [options]
```