multi-seal-mail/JAVA_PORT_NOTES.md

Java MultiMailer port notes

This skeleton now contains a first Python port of the important Java domain logic:

• Field, FieldDescription, FieldConfiguration, FieldContents
• MailTemplate with ${global::field} / ${local::field} replacement
• Recipient, RecipientList
• MailServerSettings
• MailAttachmentConfig
• MailCampaign, MailEntry, MailQueue
• attachment glob matching
• encrypted ZIP creation with pyzipper
• MIME assembly using Python's email.message.EmailMessage
• basic SMTP queue sending using smtplib

The Java Swing UI was not ported, because the planned UI is React. The SimpleJavaMail dependency was replaced by stdlib email / smtplib equivalents.

Example port of the provided MultiMailerSettings.java.example:

cd server
python -m app.mailer.examples.rechnungslegung_2026_05

Current limitations:

• IMAP append-to-Sent is not implemented yet.
• Server-side persisted campaign/job models are not implemented yet.
• Attachment storage still uses local filesystem paths in the Java-compatible domain layer; Garage object storage integration is the next layer.
• ZIP password encryption uses AES via pyzipper, not the Java zip4j implementation.
• The Java getNotSentFiles behavior is approximated and should be revisited once we define the new campaign/job data model.

Added after persistence foundation

• Queue transition for built jobs.
• Campaign-level queue/pause/resume/cancel API endpoints.
• Direct CLI queued-job processor for development without Celery.
• Celery multimailer.send_email task now sends DB-backed jobs.
• Per-campaign Redis-backed rate limiting.
• Send attempts persisted in send_attempts.
• IMAP status kept independent from SMTP status; actual IMAP APPEND remains next.

IMAP append implementation

The Python port now implements the Java-era "save to sent folder" concept as a separate post-send worker action:

• SMTP success updates send_status=sent.
• If configured, the job receives imap_status=pending.
• A separate append_sent task or CLI command appends the exact generated EML to the IMAP Sent folder.
• IMAP failures do not undo SMTP success.

This preserves the important distinction between delivery and mailbox archival.

Reporting/dashboard milestone

Added campaign reporting helpers and API endpoints. This is the backend bridge toward the first web UI: the report contains card-friendly counts, grouped statuses, attachment and issue summaries, delivery/rate-limit estimates, recent failures, and optional per-job rows. No new DB schema is required; the report is derived from persisted campaigns/jobs/attempts.