MAILWIZZ • CADDY

How to Install MailWizz on Caddy: Complete Guide

By Abhishek Sharma · Published 2026-08-21 · Last reviewed 2026-08-21

Abhishek SharmaEditor & email infrastructure writerView author profile →

Quick answer: Run MailWizz behind Caddy with PHP-FPM, automatic HTTPS and MailWizz-specific routing. This is a Caddy deployment pattern, not an official MailWizz Caddy guide. This guide focuses on the installation layer and deliberately separates application setup from email delivery, authentication and reputation.

Before you start

Caddy is attractive for PHP applications because it combines a simple configuration file with automatic HTTPS and a built-in php_fastcgi directive. The challenge with MailWizz is routing: MailWizz has multiple application entry points, so you should preserve its routing behavior instead of treating it as a generic index.php application. This guide shows the architecture and the checks you should perform before calling the installation production-ready.

Important: installation instructions can change between software releases. Use the version bundled with your license and compare the vendor's current requirements before copying commands into production. Where this article uses an adapted Caddy or Docker pattern, it is clearly labeled rather than presented as vendor certification.

What you need

A Linux VPS with root/sudo access.
A DNS hostname pointing to the server.
Caddy installed from the official distribution method.
PHP-FPM with the extensions required by your MailWizz release.
MySQL/MariaDB.
MailWizz installation package/license.
Ports 80 and 443 reachable from the internet for automatic HTTPS.

Architecture

Domain → Caddy → PHP-FPM → MailWizz → MySQL/MariaDB → Delivery server

Keeping these layers separate makes troubleshooting easier. If the web dashboard works but campaigns do not send, the problem may be in cron, the queue, the delivery server or the provider rather than in the web server. Conversely, a 502 or 500 error normally belongs to the web/PHP layer.

Step-by-step installation

1. Prepare the VPS and DNS

Point mail.example.com to the server and confirm DNS. Patch the operating system, create a sudo user and configure a firewall. Keep MySQL bound to localhost or an internal network unless remote access is explicitly required.

2. Install PHP-FPM and MySQL

Install the PHP version and extensions required by your MailWizz release, then install MySQL/MariaDB. Confirm PHP-FPM is listening on its expected Unix socket or TCP port. Caddy will forward PHP requests to that FastCGI endpoint.

3. Install MailWizz files

Place the MailWizz files in a dedicated directory such as /var/www/mailwizz. Ensure the PHP-FPM user can access the files and the directories that MailWizz needs to write to. Do not use world-writable permissions as a shortcut.

4. Build the Caddyfile

Caddy's official php_fastcgi directive is designed for PHP-FPM and is normally paired with root and file_server. Start with the official pattern, then add MailWizz-specific routing. The exact routing rules should follow the current MailWizz Nginx example because Caddy's default index.php fallback is not necessarily enough for every MailWizz endpoint.

5. Example Caddy foundation

A typical foundation is: mail.example.com { root * /var/www/mailwizz; encode gzip; php_fastcgi unix//run/php/php8.3-fpm.sock; file_server }. Before using it unchanged, compare the PHP socket and MailWizz release requirements on your server.

6. Handle MailWizz application routes

MailWizz's official Nginx configuration routes API, customer and backend paths to their respective entry points. Recreate that routing behavior in Caddy using handle/path matchers or an equivalent rewrite strategy. Test /, /backend, /customer and /api rather than checking only the homepage.

7. Let Caddy manage HTTPS

Caddy automatically provisions publicly trusted certificates when a valid hostname is configured and the server is reachable on ports 80 and 443. Confirm DNS is correct before starting the service. Check the certificate and HTTP-to-HTTPS redirect after Caddy starts.

HTTPS reminder: Use a publicly trusted certificate and test redirects, assets, login and tracking URLs after enabling TLS.

8. Complete the MailWizz installer

Open the HTTPS hostname, enter the database credentials and finish the application installer. Remove the installation directory afterward as required by MailWizz's install instructions.

9. Configure cron and delivery

Caddy only handles web traffic. MailWizz still needs its cron jobs, delivery servers, bounce servers and feedback-loop processing. Add those separately using MailWizz's backend cron list and verify them from the command line.

Cron reminder: Scheduled email applications are not complete when the dashboard loads. Confirm the scheduled jobs actually execute and produce expected logs before sending a real campaign.

10. Test Caddy-specific behavior

Check large uploads, tracking URLs, backend login, customer pages, API endpoints and static assets. Review Caddy logs and PHP-FPM logs for 4xx/5xx responses. Only after those tests should you move a live campaign into the installation.

Post-install configuration

Once the installer finishes, resist the temptation to immediately import a large list and launch a campaign. First configure the sending layer, domain authentication, bounce handling and unsubscribe behavior. Your application can be perfectly healthy while the email infrastructure is not ready for production.

1. Configure the sending service

Use a delivery service or MTA that is appropriate for your sending volume and compliance requirements. Record the exact SMTP/API endpoint, credentials, region and encryption settings. Never publish credentials in screenshots, tutorials, public repositories or support tickets.

2. Authenticate the sending domain

Publish the SPF, DKIM and DMARC records required by your chosen delivery service. If the provider gives you DKIM CNAME records, use those exact values. Avoid creating multiple conflicting SPF records. Start DMARC in a monitoring mode when you are still mapping legitimate senders, then tighten the policy once authentication is verified.

3. Configure bounces and complaints

A campaign system should not keep treating permanently failing addresses as healthy subscribers. Configure the application's bounce/complaint workflow and monitor the resulting logs. If your provider exposes feedback-loop events, connect them where the application supports it.

4. Test with a small list

Send a controlled test to addresses you own at more than one mailbox provider. Check authentication results, rendering, unsubscribe behavior, tracking, bounce handling and queue processing. Only after the end-to-end workflow passes should you increase campaign volume.

Common mistakes to avoid

Installing a PHP version without checking the application's current compatibility requirements.
Using the database root account inside the application.
Making the entire application directory world-writable.
Putting passwords or AWS credentials into a public repository.
Assuming a successful login means scheduled jobs are working.
Sending a large campaign before SPF/DKIM/DMARC and bounce handling are verified.
Treating the application as the email delivery server when it actually relies on an external SMTP/API provider.
Skipping backups before upgrades.

Troubleshooting

Caddy serves the homepage but /backend fails

The generic php_fastcgi fallback is not reproducing MailWizz's application routing. Compare your Caddy routes with the official MailWizz Nginx example and explicitly route the backend/customer/API areas.

HTTPS certificate is not issued

Check DNS and confirm ports 80/443 are reachable. Caddy's automatic HTTPS depends on the hostname resolving to the server and the server being externally reachable.

502 from Caddy

Check the PHP-FPM socket path and service status. A wrong socket path is the most common reason for a FastCGI 502.

Uploads fail

Review Caddy request/body limits, PHP upload settings and filesystem permissions. Test with a small upload first.

Cron does not run

Caddy is unrelated to cron. Run MailWizz's scheduled commands directly and check the host cron configuration.

Security checklist

Use SSH keys where possible and disable unnecessary remote access.
Keep the operating system, PHP runtime and application patched.
Use a dedicated database account.
Keep MySQL private unless remote access is explicitly required.
Use HTTPS for the administration interface.
Protect application configuration and secret files.
Back up the database and uploaded/application data.
Test restoring a backup rather than assuming it is usable.
Monitor disk, RAM, CPU, queue depth and application logs.

When should you choose this installation method?

Choose Caddy when you value simple HTTPS management and a concise web-server configuration. It is especially attractive for a single VPS where you want Caddy to terminate TLS and PHP-FPM to run the application. Because MailWizz's official web-server example is Nginx rather than Caddy, treat this as an adapted deployment and test every application route after upgrades.

Final checklist

☐ DNS resolves to the server
☐ Supported PHP/runtime is installed
☐ Database and dedicated user created
☐ Application installer completed
☐ Correct file permissions applied
☐ HTTPS works
☐ Cron/worker jobs execute
☐ Sending service connected
☐ SPF/DKIM/DMARC verified
☐ Bounce/complaint processing tested
☐ Unsubscribe tested
☐ Backup created and restore plan documented
☐ Small end-to-end test campaign completed

Related installation guides

Sources & references

This guide uses the following vendor or platform documentation. Where a deployment method is an adaptation rather than vendor documentation, that distinction is stated in the article.

Editorial note: This guide was reviewed on 13 August 2026 for structure, source alignment and internal consistency. Software vendors can change requirements, commands and supported versions; verify the current release documentation before production deployment.