README

My UNA Mail Doctor

Vendor: My UNA World Version: 0.5.0

0.5.0 — Autonomous Email Health Workflow

0.5.0 simplifies recipient-health administration into an actionable Studio workflow while preserving Mail Doctor's existing evidence and safety boundaries.

Highlights:

  • separates Email Health into Needs Attention and Healthy Email queues;
  • automatically excludes actively suppressed addresses from those queues;
  • allows administrators to select multiple Needs Attention addresses;
  • adds Suppress Selected for bulk administrator suppression;
  • adds Clear Selected for removing current health-summary records;
  • preserves historical health events, bounce evidence and suppression history when a current health record is cleared;
  • allows a cleared address to return automatically if a later recipient-health observation requires attention;
  • keeps Release available from the active suppression ledger;
  • records administrator clear actions as audit events;
  • performs no UNA account or profile mutation when clearing health records;
  • sends no email as part of a clear action;
  • retains administrator, CSRF and confirmation protections;
  • makes no database schema changes.

The 0.4.0-to-0.5.0 updater uses UNA's native file-update mechanism and does not execute SQL.

0.4.0 — Email Health & Suppression Management

0.4.0 adds Studio administration for recipient health and suppression management while preserving the existing SMTP, OAuth2 and read-only bounce-mailbox safety boundaries.

Highlights:

  • adds the Studio Email Health dashboard;
  • lists observed addresses, suppressions and health-event history;
  • provides human-readable health states, sources and timestamps;
  • adds paginated address, suppression and event views;
  • adds administrator-controlled Suppress and Release actions;
  • requires UNA administrator authorization and CSRF validation;
  • records administrator suppression and release actions atomically;
  • preserves duplicate-action idempotence and rollback safety;
  • keeps automatic bounce suppression under the existing policy and atomic observation coordinator;
  • preserves on-site and push notifications;
  • does not automatically unverify UNA accounts or profiles;
  • does not automatically clear suppression state;
  • does not add provider webhooks or member recovery workflows.

The 0.3.0-to-0.4.0 updater uses UNA's native update_files and restore_languages actions.

0.3.0 — Atomic Suppression Policy & Outbound Guard

0.3.0 introduced the suppression-policy and transactional persistence foundation used by 0.4.0.

Highlights:

  • evaluates bounce observations through a pure suppression policy;
  • persists DSN observations, health events and suppression state atomically;
  • prevents duplicate DSN observations from creating downstream state;
  • activates suppression only for explicit actionable recipient failures;
  • never automatically clears an existing active suppression;
  • intercepts outbound email through UNA system/check_send_mail;
  • treats suppressed email as intentionally handled;
  • fails open if the suppression lookup itself fails;
  • leaves on-site and push notification channels unchanged;
  • performs no automatic UNA account or profile verification changes.

0.2.0 — Bounce Intelligence Foundation

0.2.0 adds manual, read-only machine-readable DSN inspection.

  • scans up to 25 recent messages manually from Studio;
  • uses EXAMINE rather than writable SELECT;
  • reads BODYSTRUCTURE metadata to locate message/delivery-status;
  • fetches only delivery-status sections with BODY.PEEK;
  • does not fetch human-readable message bodies;
  • does not traverse attached message/rfc822 original content;
  • verifies IMAP flags are unchanged;
  • parses standard DSN recipient/status fields;
  • classifies hard, soft, policy, positive and unknown DSNs;
  • deduplicates by mailbox, UIDVALIDITY, UID, MIME section and recipient;
  • stores no raw DSN MIME section;
  • performs no suppression or UNA verification changes.

0.1.3

0.1.3 is a focused Studio presentation and compatibility update following successful Microsoft OAuth2 and read-only IMAP validation.

Changes:

  • safely renders OAuth header rows when message size is unavailable;
  • displays the installed module version dynamically in Studio;
  • removes stale 0.1.0/0.1.1 version labels from current UI;
  • corrects the legacy password IMAP adapter message now that Microsoft OAuth2 is supported by the dedicated OAuth adapter;
  • no database schema changes;
  • no changes to the validated OAuth/XOAUTH2 read-only transport.

My UNA Mail Doctor is a Studio-only email-health companion for UNA CMS and the existing UNA SMTP Mailer.

0.1.1 adds a read-only IMAP Bounce Mailbox foundation.

Features:

  • Existing UNA SMTP Mailer remains the outbound transport.
  • Post-SMTP result observation remains active.
  • Recipient and transport failures remain separate.
  • IMAP connection testing uses OP_READONLY.
  • Recent-message inspection reads message headers only.
  • Mail Doctor does not fetch bounce bodies in 0.1.1.
  • Mail Doctor does not mark, move, delete, or expunge mailbox messages.
  • Mail Doctor does not suppress email in 0.1.1.
  • Mail Doctor does not change UNA account verification.
  • IMAP credentials are encrypted with Sodium secretbox.
  • The per-site encryption key is stored outside the public web root.
  • The database never contains the plaintext IMAP password.

Authentication:

0.1.1 supports password/app-password IMAP authentication. The mailbox configuration model reserves an authentication mode for future OAuth2/provider adapters.

Security:

The credential key is created on first credential save under:

<account-home>/.my_una_mail_doctor/vault.key

The directory is restricted to 0700 and the key to 0600.

VERSION 0.1.2

0.1.2 adds Microsoft OAuth2 / modern authentication for read-only Exchange Online IMAP access.

Microsoft OAuth2 mode:

  • Uses Microsoft device-code authorization.
  • Requires no Microsoft mailbox password.
  • Requires no client secret in the UNA module.
  • Requests delegated IMAP.AccessAsUser.All plus offline_access.
  • Stores only the refresh token as Sodium-encrypted credential material.
  • Keeps device codes in the administrator PHP session only.
  • Keeps short-lived OAuth access tokens in request memory only.
  • Restricts OAuth IMAP transport to outlook.office365.com:993.
  • Requires TLS certificate validation.
  • Opens the mailbox with EXAMINE, not writable SELECT.
  • Uses BODY.PEEK for header-only inspection.
  • Does not fetch message bodies.
  • Does not move, delete, copy, expunge, or STORE message flags.
  • Verifies message flags before and after header inspection.
  • Does not activate recipient suppression.
  • Does not change UNA account verification state.

UPDATING FROM 0.1.1

Apply the dedicated 0.1.1-to-0.1.2 UNA updater. Do not uninstall the existing module and do not manually replace registered runtime files.

Microsoft OAuth requires a Microsoft Entra public-client application ID. Do not place a Microsoft client secret in the module.