# 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`:

```bash
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.