PostfixAdmin: a web interface for Postfix virtual mailboxes

What PostfixAdmin actually manages

The repository description is precise about the scope. PostfixAdmin is a web based virtual user administration interface for Postfix mail servers, and the README calls it an open source, web based interface for managing domains, mailboxes, aliases and so on.

The mechanism is a shared database. PostfixAdmin writes the users, domains, aliases and their settings into a database, and the mail server reads the same tables, so the web interface and the daemon agree by construction rather than by an API. That is why the database choice is a first class decision rather than an implementation detail.

The integration list in the README covers four things. Postfix is the mail transport itself. An IMAP or POP3 server, for example Dovecot or Courier, is what a user actually logs into. The database backend is one of SQLite, MySQL or PostgreSQL, and in the features list the supported set is expanded to MySQL, MariaDB and SQLite as well. And Fetchmail is optional, for pulling mail from a remote POP3 server.

The feature list is long and some of the entries are the reason a mail administrator would not write their own admin script. Unlimited domains, aliases and mailboxes. Optional storage quota support. Multiple password hashing formats. Vacation, autoresponder and out of office support, where users can log in, change their password and set up their own auto responder. Application specific passwords, so a mailbox can have several, one for a phone and another for a desktop. TOTP challenges for login, with optional IP address based exemptions. And storage of DKIM domain keys.

The README also points at screenshots of PostfixAdmin in action, both as admin and as user, which is the fastest way to see what the user facing side actually looks like.

The database backend is the decision you make first

Three databases are supported and the choice is made at install time rather than at runtime, which is the main structural constraint of this project.

The hosting requirements section lists the requirements and they are short. PHP 8.2 or later is required on master, and for older PHP versions the 3.3 branch supports PHP 7.0 and up. A database is required, MySQL, PostgreSQL or SQLite. And an Apache or Nginx web server capable of integration with PHP is required.

That last line is the one that surprises people who think of this as a mail server component. PostfixAdmin is not a daemon and not a plugin, it is a PHP web application with its own session handling, its own authentication and its own login pages, and it has to be reachable by the people who administer the mailboxes. In an environment where the mail server is deliberately kept off the public internet, putting a browser interface in front of it is an architectural decision with a threat model attached.

The upgrade path is also database shaped. The README notes that before a new release you should edit config.inc.php and change the version variable, and also update min_db_version in functions.inc.php if there were changes in upgrade.php. So the schema carries a version, and the running code checks it, and a mismatch between the code and the schema is a refused start rather than a broken one.

The tree shows the rest of the layout. There is config.inc.php and functions.inc.php at the root, a model/ directory for the data layer, templates/ for the pages, public/ for the web root, languages/ for translations, configs/ for the shipped configuration samples, scripts/, tests/, a debian/ directory for packaging, and a top level install.sh. The top level also holds CHANGELOG.TXT, SECURITY.md, INSTALL.md and a separate GPL-LICENSE.TXT next to LICENSE.TXT, which is worth checking against your own policy since the licence field in the repository's own metadata is one GitHub cannot classify.

master may eat your data, so use a release

The releases section of the README is the most valuable paragraph in the document, and it is a warning.

It says that while you can install PostfixAdmin from git using the master branch, master is the main development version. It may work. It may contain funky new exciting stuff. It may eat your data. If you want an easy life, use a published stable release, from the releases page or its branch, for example postfixadmin_4.0.

That is a maintainer telling users exactly which artefact to deploy, and the reason is obvious once you look at the release model. From 2025/06 the project uses SemVer releases, for example 4.0.1-beta1 rather than postfixadmin-4.0.1-beta1 for tags. The recent tags are v4.0.3 on 2026-06-13, v4.0.4 on 2026-06-27 and v4.0.5 on 2026-07-05, so the 4.0 series is a line with multiple patch releases and a branch of its own, postfixadmin_4.0.

The consequence for an operator is that there are two different upgrade paths, and they are not equivalent. Pulling master gives you the newest features and an unknown schema state, and the maintenance work in that branch is the sort that breaks a mail server's address book. Staying on a release branch gives you a known schema and a known set of changes, and the CHANGELOG.TXT file for the branch is the document to read before upgrading.

The last push to the repository was on 2026-10-13, so the master branch is moving. The project itself is not at rest, and the README is candid that the moving part is the one you should not deploy.

What the users of the interface get, and what administrators get

Two roles share the application, and the README describes them separately.

Users can log in, change their password and set up a vacation or out of office auto responder. That is the self service half, and it is the half that a mail server does not provide on its own. The README notes the integration with Squirrelmail or Roundcube via plugins, which is how the web mail client and the administration interface meet, and the VIRTUAL_VACATION/ directory at the repository root is where the vacation responder side of that lives.

Administrators get the configuration surface. Unlimited domains, aliases and mailboxes, optional storage quota, optional password expiry, which the feature list marks as beta, and multiple password hashing formats so you are not locked to one scheme. Application specific passwords are in the same list, and the reasoning is given in the README: you can have multiple passwords for a mailbox, one for your mobile device and a different one for your desktop, which is a way to revoke one device without changing the password everywhere.

The two factor story is the one that matters for a deployment. It supports TOTP challenges for login, and optional IP address based exemptions, so trusted networks can skip the second factor while a login from elsewhere still requires it.

The API surface is small and described in one line, an optional XMLRPC based API. Optional is the operative word, and it is the reason the project is usable at all in a locked down setup, since the web interface remains the primary path and the API is there for automation that has to be limited.

The development workflow and the Docker images

The development notes in the README describe a PHP project with a conventional toolchain, and the commands are short.

GitHub Actions is configured to run unit tests once something is appropriately pushed, or you can run them directly:

vendor/bin/phpunit tests

The README is careful to note that this will not test against different PHP versions, and that ACT, the nektos tool, can be used to run the tests locally, which requires Docker and therefore gives you the version matrix the plain command lacks.

The two Composer shortcuts are the other half of the workflow:

composer format
composer psalm

The first should fix styling issues such as spacing, and the second should detect some obvious errors, for example a typo in a function name or a reference to an invalid class. The repository backs both up with a .php-cs-fixer.dist.php configuration, a psalm.xml for the static analysis, and a phpunit.xml for the tests, and the security and bug fixes are in SECURITY.md and the CHANGELOG.TXT.

For deployment there is a separate set of Docker images maintained in a dedicated repository, postfixadmin/docker, which is a different thing from the application repository. The README also links a PDF that it calls probably all you need to read, a plain text description of what the project is, and the installation instructions in INSTALL.md, plus a wiki on SourceForge and an IRC channel on Libera.chat.

The related projects section is worth a look too. It points at a Dockerised GUI mailserver project, and at mailserver2/mailserver, which the README describes as a simple and full-featured mail server built as a set of multiple Docker images bundling Postfix, PostfixAdmin, Dovecot, Rspamd, Clamav, Zeyple, Sieve, Fetchmail, Rainloop, Unbound or NSD, and Træfik with Let's Encrypt or custom and self-signed certificate SSL, supporting PostgreSQL, MySQL and beta LDAP backends, with automated builds on DockerHub and integration tests on Travis CI.

Editorial conclusion

Adopt PostfixAdmin if you run Postfix with virtual mailboxes and you want a browser based way to create mailboxes, aliases and quotas, and if you can live with a PHP web application and a database schema in your mail infrastructure. Do not adopt it if you run a mail server without virtual users, or if you want the master branch, and do not adopt it if your policy forbids a login with a password plus a second factor in front of a mail administration panel. Verify first which release branch you are on, that the database schema you create matches the min_db_version in functions.inc.php for that release, and that your web server and PHP version meet the stated requirements of 8.2 and later on master.

Frequently asked questions

Official sources

1. Issues
2. postfixadmin/postfixadmin on GitHub
3. Project website
4. README
5. Releases