INSTALLATION
============

1. Install the module in a Drupal project with Composer:

       composer require drupal/postfix_admin

2. Enable the Postfix Admin module with Drush or from the Extend page.

3. Configure Postfix to read Drupal's routing tables using the SQL map contract
   below. The module creates these tables; it does not configure mail transport.

4. Open `/admin/config/services/postfix_admin/settings` and choose whether alias email
   addresses require confirmation. Database credentials belong in Postfix's
   protected SQL map files, not this form.

5. Add a domain before adding mailboxes or aliases.

REQUIREMENTS
============

* Drupal 11.4 or later, including Drupal 12.
* PHP 8.3 or later.
* A separately configured Postfix service with access to the routing tables.

SQL MAP INTEGRATION
===================

See docs/sql-map-contract.md and examples/postfix/ for the versioned SQL map
contract, least-privilege database access, and safe upgrade/uninstall steps.
The examples must be configured and deployed separately from the Drupal module.

UPGRADING FROM DRUPAL 8
=======================

1. Back up both the database and the deployed Drupal code and configuration.
   Test that the backup can be restored before deploying the update.

2. Stop mailbox administration writes for the upgrade window, deploy the new
   code, and run `drush updatedb`.

3. The update changes Drupal entity type IDs to `postfix_admin_*` but retains
   the populated `domain`, `mailbox`, `alias`, and `alias_domain` SQL tables.
   It also migrates role permissions, core entity displays, and address
   reservations. If custom fields are attached to these entities, the update
   stops before changing entity definitions; migrate those fields separately.

4. Verify entity row counts, role access, and representative Postfix lookups
   before reopening mailbox administration. The update also expands mailbox
   password storage and removes the persisted password-confirmation field.

5. Rotate every mailbox password that may have been stored by an older schema.
   Expanding the column cannot reconstruct a hash that was already truncated.
   Also rotate credentials formerly stored in legacy `postfix_admin.config.*`
   configuration.

6. If rollback is required, restore the database backup together with the
   matching previous code. Downgrading the updated schema in place is not
   supported.
