# MassMailer

Windows HTA application for individual marketing emails for a 9 x 12 postcard business.

## Current build

- Creates an Access `.mdb` with versioned tables for contacts, suppressions, templates, campaigns, attempts, protected secrets, and audit records.
- Checks the configured provider, process architecture, MDB, and schema before launching the HTA.
- Imports UTF-8 contacts from a previewed CSV and records global suppressions.
- Imports constrained, well-formed HTML templates from `TEMPLATE_ROOT`, snapshots local PNG/JPEG/GIF images into the MDB, and previews the stored version in an untrusted HTA frame.
- Stores the SMTP password as a Windows user-protected value in the MDB through an interactive local setup action.
- Offers an explicit, single-message SMTP transport test to the configured `SMTP_TEST_TO` address.
- Reviews a campaign against unsuppressed contacts, adds an advertisement, postal, and reply opt-out footer, tests the reviewed message only to the internal inbox, and records approval in a paused state.
- Uses tabs for Overview, SMTP, Contacts, Templates, Campaigns, Sending, and Reports. Contacts includes import and global suppression.
- Sends approved campaigns only while the HTA is open, with a configurable account-wide gap between attempts. It pauses on restart and uncertain outcomes, rechecks suppression before each send, and requires a fresh mailbox opt-out review before resuming.
- Sends a test of an approved campaign to the internal inbox without advancing delivery counts, and exports delivery and attempt CSV reports to `REPORT_DIR`.
- Runs routine PowerShell helpers without opening console windows. The password setup action opens a console so the password can be entered privately.

Live marketing dispatch has passed disposable-database pickup tests. It still needs an owner-run internal pilot and inbox review before use with business contacts. Closing the HTA stops new send attempts; an SMTP attempt already in progress may finish.

## Setup on this PC

1. Copy `config.example.ini` to `config.ini` and edit local settings. Set `SMTP_TEST_TO` to the owner-controlled test inbox. `BUSINESS_POSTAL_ADDRESS` remains blank until you supply it; campaign review and approval require it. Never place the SMTP password in the INI.
2. Run `C:\Windows\SysWOW64\cscript.exe //nologo tools\init-db.vbs` once to create `data\MassMailer.mdb`. It refuses to overwrite an existing database.
3. Run `Start-MassMailer.cmd`. The launcher selects the configured script architecture and opens the MDB before starting the HTA. Use `C:\Windows\SysWOW64\cscript.exe //nologo tools\launch.vbs check` to check startup without opening the UI.
4. Import a UTF-8 CSV with an `email` header. Optional columns are `business_name`, `source_reference`, and `acquired_at` (`YYYY-MM-DD`). Supply a source reference in the CSV or the form; preview and review rejected rows before importing.
5. Enter opt-out replies in the suppression form. Press **Set or rotate SMTP password** to enter the password locally, then press **Send one internal test**. The owner reports that this authenticated SMTP test worked on this PC; detailed received-image rendering has not been separately recorded.
6. Put template files under `TEMPLATE_ROOT` and import them from the HTA. The accepted HTML subset and example are in [templates/README.md](templates/README.md). Imported versions are immutable snapshots. The template preview shows stored content, while the campaign preview adds the full footer.
7. Fill in `BUSINESS_POSTAL_ADDRESS` in local `config.ini`. Enter a campaign name and subject, select an imported template, and press **Review message and recipients**. After checking the full preview, send the campaign-specific test to `SMTP_TEST_TO` and confirm it arrived. Approval records paused deliveries; it does not start sending.
8. In **Sending**, send an optional test of the approved snapshot to `SMTP_TEST_TO`. Check the monitored reply mailbox, record opt-outs under **Contacts**, then mark the mailbox reviewed and explicitly resume the selected campaign. Keep the HTA open while sending. Use **Pause all** to stop new attempts and **Reports** to export delivery and attempt histories.

Local `config.ini`, MDB files, logs, backups, and temporary test data are ignored by Git.

## Verification

Run `powershell.exe -NoProfile -ExecutionPolicy Bypass -File tools\test-contact-flow.ps1` for disposable-MDB setup, protected secret, contact, suppression, and MIME pickup checks. `tools\test-template-flow.ps1` checks template import and preview. `tools\test-campaign-flow.ps1` checks review, tests before and after approval, and paused approval. `tools\test-dispatch-flow.ps1` checks session guard, pacing, restart, suppression, uncertain outcomes, reconciliation, and reports with local pickup files. `tools\test-hta-syntax.ps1` checks JScript syntax; `tools\test-hta-startup.ps1` opens a hidden HTA, checks the live session guard, and closes only that test instance. `tools\test-smtp-capabilities.ps1` checks the server STARTTLS handshake without sending mail.

## Planning documents

- [Project brief and open decisions](.specs/project/PROJECT.md)
- [Requirements, Scrum stories, and sprint outline](.specs/features/mass-mailer/spec.md)
- [Architecture and data model](.specs/features/mass-mailer/design.md)
- [Test plan and release gates](.specs/features/mass-mailer/test-plan.md)
- [Example SMTP configuration without a password](config.example.ini)
- [Access provider probe for 32-bit and 64-bit hosts](tools/probe-mdb-providers.vbs)

System-wide settings belong in the INI; campaign settings, templates, contacts, queue state, and protected secrets belong in the Access MDB. Backups and a restore drill remain to be implemented.