Set up your SMTP Wizard

Overview

The SMTP Wizard has two parts:

• The deployment wizard (PHP) — runs on your cPanel hosting. You enter a target server's IP and root password, pick a domain, and it remotely installs and configures a complete SMTP engine over SSH, then hands you the exact DNS records to publish.
• The access layer (Node.js) — the public landing page, the Cryptomus crypto-payment checkout, the gated builder dashboard, and the admin panel for approving free IPs.

Requirements

For the cPanel wizard (PHP)

• cPanel/PHP hosting running PHP 8.1+
• The ssh2 PHP extension or the bundled phpseclib fallback (already included in api/vendor/ — no action needed if ssh2 is missing)
• curl enabled (for the Cloudflare DNS auto-setup feature)

For the target mail server

• A fresh VPS with a public IPv4 address and root SSH access
• Supported OS: AlmaLinux, Rocky, CentOS, RHEL, Fedora, Ubuntu, or Debian
• Ports 25, 587, 8000, and 80 open (the wizard configures the firewall for you)
• Port 25 not blocked by your provider (many block it by default — request unblocking)

For the access layer (Node app)

• Node.js 18+ on whatever host serves your landing page/checkout
• A Cryptomus merchant account for crypto payments

Install on cPanel

Configure the wizard

On the wizard's Mail Identity Configuration screen, fill in:

Run deployment

Click Start Deployment. The wizard streams a live log as it works through these stages on your VPS:

1. TCP + SSH pre-flight checks and OS detection
2. Fixes server DNS resolution if broken, sets the hostname and /etc/hosts
3. Configures the firewall and removes any competing MTAs (Postfix/Sendmail/Exim) holding ports 25/587
4. Installs the SMTP engine, generates a 2048-bit DKIM key, and writes the policy config
5. Optionally installs Prometheus, Grafana, and the Admin UI dashboard
6. Runs a final health check and verifies the SMTP banner

When it finishes, the wizard shows your DNS records and access URLs. Deployment typically takes 3–8 minutes depending on the server.

DNS records

After deployment, publish these records at your DNS provider. The wizard generates them with your real values — the table below shows what each one is for.

Cloudflare auto-setup

If your domain is on Cloudflare, the wizard can publish every record (except PTR) for you. There are two ways:

• 1-click Connect (recommended) — click Connect Cloudflare. If you're signed into Cloudflare in your browser, you'll see a consent screen asking to allow DNS changes. Click Allow and the wizard locates your zone and fixes the DNS automatically — no token copying.
• API token — paste a scoped token (Zone → DNS → Edit). Always available as a fallback.

Enabling 1-click Connect (one-time setup)

The 1-click flow uses Cloudflare OAuth, so you register an OAuth client once:

1. Go to Cloudflare dashboard → Manage Account → OAuth clients → Create client.
2. Set Grant type = Authorization Code, Token auth = Client Secret, and Redirect URL = https://YOUR_DOMAIN/installer/api/cf_oauth_callback.php.
3. Select the DNS edit and Zone read scopes, then create the client and copy the Client ID + Client Secret.
4. Edit installer/api/cf_config.php and fill in client_id, client_secret, and redirect_uri.

IPv4 & IPv6 servers

The wizard supports both IPv4-only and dual-stack (IPv4 + IPv6) servers automatically:

• IPv4-only servers — you get A, MX, SPF (ip4: only), DKIM, DMARC, and an IPv4 PTR. No AAAA or IPv6 entries are generated, so there's nothing extra to clean up.
• Dual-stack servers — if a globally routable IPv6 address is detected, the wizard additionally publishes AAAA records and adds an ip6: term to SPF, plus an IPv6 PTR reminder. The engine prefers IPv6 for outbound with automatic IPv4 fallback.

Send a test email

Use the wizard's built-in test, or send manually. Authenticated submission uses port 587 with your master password (default Lurstan — change it). Any username works; the password is what authorizes relay.

swaks --server mail.example.com --port 587 \
  --auth LOGIN --auth-user you@example.com \
  --auth-password 'YOUR_MASTER_PASSWORD' \
  --from you@example.com --to test@gmail.com \
  --header "Subject: Hello from SMTP Wizard" \
  --body "It works!" --tls

Unauthenticated connections are rejected with 550 5.7.1 relaying not permitted, so your server can't be used as an open relay.

Change domain

To repoint an existing server at a new sending domain, use the wizard's Change Domain action. It backs up the current config, generates a fresh DKIM key for the new domain, rewrites the policy atomically, updates the hostname, and restarts the engine — then gives you the new DNS records. Previous configs are saved under /opt/<engine>/etc/backups/ on the server.

Payment gateway (Cryptomus)

The access layer is a small Node.js app that serves the landing page, the checkout, and the builder dashboard.

1. Configure

cp .env.example .env
# then edit .env:
CRYPTOMUS_MERCHANT_ID=your-merchant-uuid
CRYPTOMUS_PAYMENT_API_KEY=your-payment-api-key
APP_BASE_URL=https://yourdomain.com   # must be reachable by Cryptomus
UNLOCK_PRICE_USD=100
ADMIN_TOKEN=a-long-random-secret

2. Run

npm install
npm start          # serves on PORT (default 3000)

3. How a purchase flows

1. A visitor clicks Unlock, enters their email, and is sent to the Cryptomus crypto checkout.
2. Cryptomus calls your /api/cryptomus/webhook (signature-verified) when payment confirms.
3. The server issues a license key and unlocks the dashboard, where the buyer enters their server IP + SMTP details to build once.
4. The build consumes the payment. Rebuilding on that IP requires paying again.

Admin IP allowlist (free forever)

You can grant specific IPs free, unlimited SMTP builds — no payment, ever. Set ADMIN_TOKEN in .env, then open the admin panel:

https://yourdomain.com/admin.html

Sign in with your admin token and add an IP with an optional note. From then on, building SMTP on that IP is free and never consumes a payment. Remove the IP to require payment again.

API (if you prefer scripting)

# Add an IP to the free allowlist
curl -X POST https://yourdomain.com/api/admin/allowlist \
  -H "x-admin-token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.42","note":"in-house server"}'

# List approved IPs
curl https://yourdomain.com/api/admin/allowlist -H "x-admin-token: YOUR_ADMIN_TOKEN"

# Remove one
curl -X DELETE https://yourdomain.com/api/admin/allowlist/203.0.113.42 \
  -H "x-admin-token: YOUR_ADMIN_TOKEN"

Build log & abuse control

The admin panel's Build log tab records every SMTP build for full accountability. Each entry captures:

• The builder's IP and geolocation (country, city, and flag) plus their browser user-agent
• The target/sending server IP and its geolocation
• The full SMTP credentials (host, port, username, password) and the dashboard UI + metrics URLs
• Whether it was a paid or free (allowlisted) build, and the buyer's email/license

If a server starts abusing the service for spam, click Block next to its entry (or add it under the Blocked IPs tab). Blocked server IPs are immediately refused at /api/smtp/build and cannot build again until you unblock them.

# Block a server IP for abuse
curl -X POST https://yourdomain.com/api/admin/block \
  -H "x-admin-token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.42","reason":"spam complaints"}'

# Review the full build log
curl https://yourdomain.com/api/admin/builds -H "x-admin-token: YOUR_ADMIN_TOKEN"

Health & monitoring

The wizard includes a health check that reports engine status, port 25/587 listening state, queue depth, DKIM key presence, PTR, disk/RAM/load, and recent logs. If you enabled them:

• Prometheus scrapes engine metrics at http://server:8000/metrics (UI on port 9090).
• Grafana dashboards on port 3000.
• Admin UI dashboard at http://mail.example.com/ui/.

The Node access layer exposes /api/health returning JSON status for uptime checks.