Skip to content

Getting started

Requirements

  • Drupal 11.4 or later, including Drupal 12.
  • PHP 8.3 or later.
  • Composer for installing the contributed module.
  • A separately managed Postfix service if the Drupal data will be used for mail routing.

Install the module

From the directory containing the Drupal site's composer.json, run:

composer require 'drupal/postfix_admin:^1.0'

Enable the module through Extend or with Drush:

drush pm:enable postfix_admin
drush cache:rebuild

Run normal Drupal database updates after upgrading an existing installation:

drush updatedb
drush cache:rebuild

Grant access

Grant only the permissions needed by each operator. Administer Postfix Admin controls the module settings. Domain, mailbox, alias, and alias-domain records have separate create, administer, edit, delete, and published/unpublished view permissions.

The optional Postfix Admin Console Recipe can create a dedicated postfix_administrator role with the complete operator permission set. It does not assign the role to a user.

Configure the administration workflow

Open Configuration → Web services → Postfix Admin settings to display Domain list, or go directly to /admin/structure/postfix_admin/domain. The Settings tab opens /admin/config/services/postfix_admin/settings.

The local tasks provide:

  • Domain list
  • Alias list
  • Mailbox list
  • Alias domain list
  • Settings
  • +, which opens the add form for the resource list currently displayed

Create a domain before creating a mailbox, alias, or alias domain. The relevant forms link back to the domain add form when no domain exists.

Use Settings to choose whether alias addresses require confirmation and to set the list page size. Supported page sizes are 15, 20, 25, 50, and 100.

Connect Postfix

The module does not change the Postfix service. Review the Postfix SQL map contract, copy the applicable files from examples/postfix/ into the protected Postfix configuration managed by the site, and supply credentials through that environment.

Use a dedicated database account with read-only access to the required routing columns. Never commit database credentials, production host details, or site secrets. Validate each lookup with postmap -q before switching live maps.

Uninstall safely

Drupal blocks normal uninstall while Postfix Admin entities exist. Before removing the module, migrate any live routing dependency, switch Postfix away from these tables, verify mail routing, remove the Drupal entities through an approved process, and retain a restorable backup.