# Email & webmail
URL: https://synquic.tech/docs/guides/email-webmail.md

Run your own self-hosted mail server and a webmail app with Synq — provision it, manage domains and mailboxes, and put an inbox in the browser.

import { Step, Steps } from 'fumadocs-ui/components/steps';

Most people rent their email from someone else — Gmail, Outlook, and the like. Synq lets you run the
whole post office yourself: a real mail server on your own machine, with your own domain, that sends and
receives mail and even gives you a webmail inbox in the browser. Think of it as the difference between renting
a PO box and owning the building.

You're not limited to one, either. Each mail server runs on its own host (one mail setup per server), and
Synq keeps them all in a single **Mail servers** list — provision as many as you like and switch between
them from one place. A lone server opens straight into its admin panel; once you have more than one, you land
on the list first.

This is a big, hands-on feature, so this guide stays at the map level: what each screen does and the order you
go through them. The fiddly bits — the exact DNS records and the reverse-DNS setup — are called out where they
happen, because the wizard walks you through those live.

<Callout title="Self-hosted only" type="warn">
Email runs entirely on your own infrastructure: Synq installs the mail stack on one of your servers over
SSH. The **Emails** item appears in the sidebar of a self-hosted install, which every Synq install is. See
[Installation](/docs/getting-started/installation) if you haven't set Synq up yet.
</Callout>

<Callout title="What you need first">
- Synq running self-hosted, with at least one **connected server** (a clean Ubuntu or Debian machine is
  recommended). See [Connect your own server](/docs/guides/custom-servers) if you don't have one yet.
- A **domain name** you control, where you can edit DNS records.
- **Port 25 open** for outbound mail — some hosting providers block it by default, so check before you start.
- Access to your **VPS provider's panel** (for the reverse-DNS step near the end).
</Callout>

A few words you'll see a lot:

- **Mail server** — the software that actually sends and receives email. Synq installs a well-known stack
  (Postfix, Dovecot, and anti-spam tools) for you.
- **Mailbox** — one email account, like `you@yourdomain.com`, with its own password and inbox.
- **DNS records** — public settings for your domain that tell the rest of the internet where your mail lives.
- **Webmail** — an email app you open in a browser, so you don't need to configure a separate mail app.

## Step 1 — Provision a mail server

<Steps>

<Step>

### Open the Emails page

In the sidebar, click **Emails**. With no mail server set up yet, you land straight on the **Mail Server
Setup** form. If you already run **several** mail servers, you'll see a list of them first — click **Add mail
server** to start another. (With a single existing server, Synq opens it straight to its admin panel; use
the **Add mail server** button there to set up another.)

</Step>

<Step>

### Pick a server and a domain

Choose which of your connected servers the mail stack should run on. If you only have one, Synq picks it
for you.

Then fill in two things:

- **Domain** — your bare domain, like `example.com` (no `https://`, no path). Synq shows you that your
  mail server will live at `mail.example.com`.
- **Admin Password** — the password for the first mailbox, `postmaster@yourdomain`. You'll use it to log in
  after setup. Don't want to think one up? Click **Generate** for a strong random one, then copy it somewhere
  safe.

The right-hand panel lists exactly what gets installed — the mail stack, an automatic **Let's Encrypt** SSL
certificate, the DNS records you'll need, and the admin panel — plus the prerequisites (a domain with DNS
access, port 25 open, a clean server).

</Step>

<Step>

### Press Start Setup and watch it run

Click **Start Setup**. Synq connects to your server and works through the install one step at a time
(system update, mail stack, SSL, and so on), streaming the logs live — like watching the oven through the
glass door. You don't have to do anything while it runs.

Partway through, it pauses twice to wait for you. Those two pauses are the next two steps.

</Step>

<Step>

### Publish your DNS records

The install stops and shows a banner: **Publish DNS records before continuing**. Below it are cards — one per
record (things like MX, SPF, DKIM, and DMARC) — each with a **Copy value** button.

Go to wherever your domain's DNS is managed, add each record, and come back. Then click **I've set the records
- continue**.

<Callout title="Why this matters" type="info">
Email delivery breaks without these records — they're how Gmail and Outlook decide your mail is real and not
spam. If you host DNS at a supported provider, the banner also offers **Auto-configure DNS**, which pushes the
records for you. Otherwise, copy them in by hand. For a gentler intro to DNS, see [Custom domains](/docs/guides/custom-domains).
</Callout>

</Step>

<Step>

### Set reverse DNS (PTR)

Next comes a second banner: **Set reverse DNS (PTR) before continuing**. This one is different — you set it at
your **VPS provider's panel** (Hostinger, DigitalOcean, AWS, and so on), **not** at your DNS provider.

The banner shows your server's IP address and the value to point it at (`mail.yourdomain`). Set it there, wait
a few minutes for it to take effect, then click **I've set the PTRs - continue**.

<Callout title="Reverse DNS in one line" type="info">
Normal DNS turns a name into an IP address; reverse DNS (a **PTR** record) turns the IP back into a name. Big
mail providers reject mail from servers whose reverse DNS doesn't match — so this step is not optional.
</Callout>

</Step>

<Step>

### Done

Synq finishes the SSL step and the page flips to the **admin panel**. Your mail server is live. It also
offers to send a quick welcome test email so you can confirm mail is flowing.

</Step>

</Steps>

<Callout title="Already have a mail server from Synq?" type="info">
If you set one up before and Synq lost track of it (for example, you moved to a new computer), you don't
have to reinstall. On the setup form, click **Already have a mail server? Adopt it**, pick the server, and
click **Scan server**. If a mail stack is found, click **Adopt** — it's brought back into the dashboard with
your mailboxes and data left untouched.
</Callout>

## Step 2 — Manage domains and mailboxes

Once a server is provisioned, the **Emails** page becomes its admin panel — your home base for running the mail
server. It's organized into tabs:

- **Overview** — the hostname, the webmail button, mail stats (domains, mailboxes, storage), and quick links.
- **Domains** — add extra domains you want to receive mail for. A new domain accepts mail once its MX record
  points at this server.
- **Mailboxes** — create email accounts under a domain. Each one is a login (`name@domain`) with its own
  password and quota. This is also where you change the `postmaster` password later.
- **Aliases** — forwarding addresses, and a catch-all for everything else at a domain.
- **Notifications** — get told in a notification channel (Slack, Telegram, Discord, a webhook) when mail
  arrives at one of these addresses.
- **Sending** — how outbound mail leaves: direct, or relayed through a provider. **Send test email** lives
  here too.
- **DNS** — a reference copy of every record each domain needs, with a **Verify** button that checks whether
  they're actually published.
- **Health** — live status of each mail process, refreshed automatically.
- **Backup** — snapshot the mail server (accounts, messages, keys) to one of your backup destinations.
- **Advanced** — the IMAP/SMTP connection settings for wiring up a mail app by hand, plus power-user actions
  like restarting the stack or re-running the wizard.

<Callout title="Adding a second domain" type="info">
When you add a domain under the **Domains** tab, Synq generates its DNS records (including a fresh DKIM
key). Publish those at your DNS provider — the **DNS** tab shows them and can verify them — before you rely on
that domain for mail.
</Callout>

## Step 3 — Deploy the webmail app

A mail server on its own has no web page — you'd point a mail app at it. Synq can also deploy **Zero**, a
webmail app, so you (and your users) get an inbox in the browser instead.

<Steps>

<Step>

### Start from the Overview tab

On the admin panel's **Overview** tab, find the mail server card and click **Deploy webmail**. This opens the
**Deploy webmail** screen.

</Step>

<Step>

### Choose where it runs and at which address

Two choices:

- **Deploy to**: where the webmail app should run. You can put it on **this mail server** or on **another one
  of your servers**.
- **Domain** — the web address people will open to reach the inbox. It defaults to `mail.yourdomain`. Whatever
  you pick, its DNS must point at the deploy target — the on-screen hint tells you what's expected for the
  option you chose.

The summary panel on the right restates your target and domain.

</Step>

<Step>

### Press Deploy webmail

Click **Deploy webmail**. Synq creates a project and a deployment for you and drops you on the standard
**build screen**, which streams the logs live — the same screen you'd see [deploying any app](/docs/guides/deploy-from-github).
When it's done, the Overview card's button changes to **Open webmail**, which opens your inbox in a new tab.

</Step>

</Steps>

<Callout title="Upgrading a webmail from Synq 0.6.1 or earlier" type="warn">
Webmail used to ship as a prebuilt bundle instead of an app, and those older installs can't be redeployed —
they're replaced. The Overview card shows a **Replace webmail** link, and the deploy screen explains what goes
before the button does anything: the old webmail's project, container and sign-in sessions. Your mailboxes,
domains and every message stay on the mail server, untouched — everyone just signs in to the new inbox again.
</Callout>

## CLI

The provisioning flow works from the CLI too (webmail deploy is dashboard-only for now). Every `mail` command
is self-hosted only.

```bash
# Start the install on a server for your domain (streams live)
synq mail setup <serverId> --domain example.com

# When it pauses for DNS: publish the records, then acknowledge and resume
synq mail dns-ack <serverId>
synq mail setup <serverId> --domain example.com --start-step <n>

# When it pauses for reverse DNS: set the PTR, then acknowledge and resume
synq mail ptr-ack <serverId>
synq mail setup <serverId> --domain example.com --start-step <n>

# Check where things stand at any time
synq mail status <serverId>

# Re-adopt an existing install (after losing the dashboard's record of it)
synq mail scan <serverId>
synq mail adopt <serverId>
```

<Callout title="Tip" type="info">
When the install pauses, the CLI prints the exact `--start-step` number to resume from. Copy it into the next
`mail setup` command and it picks up right where it left off.
</Callout>

## Troubleshooting

<Callout title="I don't see an “Emails” item in the sidebar" type="warn">
Email is a self-hosted feature, and every Synq install is self-hosted, so the item should be there.
Hard-refresh the panel, and if it's still missing, ask an admin whether your role has access to
**Mail servers**.
</Callout>

<Callout title="The “Check Port 25” step warns that port 25 is blocked" type="warn">
This step is a check, not a wall — the install keeps going even when it warns. Direct-to-MX sending needs
outbound port 25. Many hosting providers block it by default, including AWS. You can
finish setup and route sending through an SMTP provider from the **Sending** tab (Amazon SES, and similar),
then use **Sending → Send test email** to confirm mail flows.
</Callout>

<Callout title="“Verify Public Mail Ports” warns about TCP 25 but 465/587/993 are open" type="warn">
On a single-server install the probe runs from the same machine it is testing. An outbound port-25 restriction
can make `mail.example.com:25` time out even when the daemon listens on a non-loopback interface. If all three
client ports complete a TCP handshake and only TCP 25 times out, setup continues with a warning. Connection
refusals, routing errors, missing or loopback-only listeners, and client-port failures still stop setup.

Health keeps inbound SMTP **unverified**. Check TCP 25 from an independent host or send a test message from
another mail provider: open client ports do not prove that other mail servers can reach your inbound SMTP.
If receiving fails, check inbound TCP 25 in the host and provider firewalls. A relay configured in **Sending**
handles outgoing mail only.
</Callout>

<Callout title="Mail sends but lands in spam" type="warn">
This is normal for a brand-new domain — providers are cautious for the first day or two. Make sure your DNS
records (SPF, DKIM, DMARC) and your reverse DNS (PTR) are all published and verified: use the **DNS** tab's
**Verify** button and the **Health** tab. Marking early test messages as "not spam" speeds things up.
</Callout>

<Callout title="A record won't verify" type="error">
DNS changes can take a few minutes (sometimes longer) to spread. Give it time, then re-check on the **DNS**
tab. Double-check you pasted the value exactly and added it to the right domain.
</Callout>

## Related guides

<Cards>
  <Card title="Custom domains" href="/docs/guides/custom-domains" description="How DNS and automatic HTTPS work for your apps — useful background for the mail DNS steps." />
  <Card title="Deploy from GitHub" href="/docs/guides/deploy-from-github" description="Understand the build screen you land on when deploying webmail." />
  <Card title="Connect your own server" href="/docs/guides/custom-servers" description="Add the machine your mail stack runs on, over SSH." />
</Cards>