---
name: emailwiz
description: emailwiz recipe for open-forge. Covers using the emailwiz bash script to auto-configure a complete self-hosted email server (Postfix + Dovecot + SpamAssassin + OpenDKIM). Upstream: https://github.com/LukeSmithxyz/emailwiz
---

# emailwiz

Bash script that automatically installs and configures a complete self-hosted email server stack on a fresh Debian/Ubuntu VPS. Installs and links: **Postfix** (send/receive), **Dovecot** (IMAP/POP3), **SpamAssassin** (spam filtering), **OpenDKIM** (email authentication), **Certbot** (SSL), and **fail2ban** (security). No database, no web UI — uses standard Unix system users for accounts. Upstream: <https://github.com/LukeSmithxyz/emailwiz>.

**License:** GPL-3.0

> **Note:** emailwiz is a **setup script**, not a running application. It configures standard mail server software that then runs as system services (Postfix, Dovecot, etc.).

## Compatible install methods

| Method | Upstream | First-party? | When to use |
|---|---|---|---|
| `emailwiz.sh` (curl + bash) | https://github.com/LukeSmithxyz/emailwiz | ✅ | Fresh Debian/Ubuntu VPS; one-shot setup |

## Prerequisites

Before running the script:

1. **Debian or Ubuntu server** with root/sudo access
2. **Static IP** for the server
3. **DNS A/AAAA records** pointing your domain (and `mail.yourdomain.tld`) to the server IP
4. **Reverse DNS (PTR) record** set to `mail.yourdomain.tld` — request from your VPS provider
5. **Mail ports unblocked** by VPS provider (25, 465, 587, 993, 995) — many providers block these by default; open a ticket

## Inputs to collect

| Phase | Prompt | Format | Applicability |
|---|---|---|---|
| dns | "Domain name?" | e.g. example.org | Required; set as /etc/mailname |
| dns | "Mail subdomain prefix?" | Default: `mail` (overridden by `MAIL_SUBDOM` env var) | Required |
| dns | "IPv4 A record points to this server?" | Yes/No (script checks) | Required |
| certbot | "Let's Encrypt cert for mail.domain?" | Script auto-requests via certbot | Needs port 80 open |

## Installation

```bash
# Option 1: Shorter URL
curl -LO lukesmith.xyz/emailwiz.sh
# Option 2: Directly from GitHub
curl -LO https://raw.githubusercontent.com/LukeSmithxyz/emailwiz/master/emailwiz.sh

# Make executable and run as root
chmod +x emailwiz.sh
sudo bash emailwiz.sh
```

When Postfix's dialog prompts appear, select **"Internet Site"** and enter your bare domain (e.g. `example.org`, not `mail.example.org`).

## What the script installs

| Package | Role |
|---|---|
| Postfix | MTA — sends and receives email (SMTP) |
| Dovecot | MDA — delivers mail to clients via IMAP/POP3 |
| SpamAssassin | Spam filtering |
| OpenDKIM + opendkim-tools | DKIM signing for outbound mail |
| Certbot | TLS/SSL certificates (Let's Encrypt) |
| fail2ban | Brute-force protection for Postfix/Dovecot |
| bind9-host | DNS lookup utilities |

## Software-layer concerns

### Key config files (generated by script)

| File | Purpose |
|---|---|
| `/etc/mailname` | Server's domain name |
| `/etc/postfix/main.cf` | Postfix main configuration |
| `/etc/dovecot/dovecot.conf` | Dovecot configuration |
| `/etc/opendkim.conf` | OpenDKIM configuration |
| `/etc/spamassassin/local.cf` | SpamAssassin custom rules |
| `/etc/letsencrypt/live/mail.domain/` | TLS certificates |

### Ports

| Port | Protocol | Purpose |
|---|---|---|
| 25 | TCP | SMTP (receive inbound mail) |
| 465 | TCP | SMTPS (submission, legacy SSL) |
| 587 | TCP | Submission (STARTTLS, recommended for clients) |
| 993 | TCP | IMAPS |
| 995 | TCP | POP3S |

### Mail accounts

Accounts are standard Linux system users:
```bash
# Add a new email account
useradd -m -s /bin/false user@example.org
passwd user@example.org
```

No web UI included. Use Thunderbird, mutt/[mutt-wizard](https://github.com/lukesmithxyz/mutt-wizard), or K-9 Mail as clients.

## Post-install DNS records

After the script completes, it outputs the DNS records you must add. They look like:

```
@               MX   10  mail.example.org
mail._domainkey TXT      v=DKIM1; k=rsa; p=<uniquely-generated-key>
_dmarc          TXT      v=DMARC1; p=reject; rua=mailto:dmarc@example.org; fo=1
@               TXT      v=spf1 mx a: -all
```

The DKIM TXT record **is uniquely generated per installation** and must be added after running the script.

## Upgrade procedure

The script configures standard Debian/Ubuntu packages. Upgrades are via normal system package management:

```bash
apt-get update && apt-get upgrade
```

Re-running `emailwiz.sh` on the same server will re-apply config. Back up `/etc/postfix/`, `/etc/dovecot/`, and `/etc/opendkim/` before re-running.

## Gotchas

- **VPS mail port blocks.** Most VPS providers block port 25 by default. You must request they unblock mail ports before inbound mail will work.
- **Reverse DNS (PTR) required.** Without a PTR record matching `mail.yourdomain.tld`, many receiving servers will reject your mail as spam.
- **DKIM key is unique.** The DKIM TXT DNS record is generated at install time and cannot be copied from elsewhere — you must add the output from your specific install run.
- **No web UI.** emailwiz does not install Roundcube or any webmail. Use desktop/mobile mail clients (Thunderbird, K-9 Mail, mutt).
- **Debian/Ubuntu only.** The script targets Debian-based systems. Does not support RHEL/Fedora/Alpine.
- **One domain per server.** The script is designed for a single domain. Multi-domain setups require manual Postfix virtual domain configuration.
- **Self-signed cert option.** Set `selfsigned="yes"` in the script for isolated/VPN-only setups where Let's Encrypt isn't reachable.

## Upstream docs

- GitHub README: https://github.com/LukeSmithxyz/emailwiz
- mutt-wizard (client setup): https://github.com/lukesmithxyz/mutt-wizard
- LandChad.net guides (companion): https://landchad.net
