MassMailer/.specs/features/mass-mailer/spec.md

MassMailer requirements and Scrum backlog (draft)

Status: Draft pending the open technical and content decisions in ../../project/PROJECT.md.

Functional requirements

1. Import CSV with column mapping, syntax checks, duplicate detection, source and import timestamp; show rejected rows before committing.
2. Maintain contacts and a global suppression list. Re-imports must never clear a suppression.
3. Import and manage reusable HTML templates and their local image files. Create campaigns with a selected, frozen template and image version, truthful subject, sender identity, postal address, clear ad identification, and the confirmed reply-mailbox opt-out route.
4. Preview rendered messages and send a test to an approved internal address without advancing the live queue.
5. Select eligible recipients, review counts and sample messages, approve, and schedule a campaign start instant. Dispatch occurs only while the HTA is open; overnight/weekend sends are allowed if it remains open.
6. Send one recipient at a time at the configured minimum interval; pause/resume/cancel safely. Closing the HTA stops new sends. No backlog burst after sleep, closure, or downtime; reopening requires explicit resume.
7. Record attempt, provider response, accepted/failed/uncertain state, timestamps, and campaign summary. Provider acceptance is not proof of delivery.
8. Retry only transient failures with bounded attempts and provider-directed delay. Do not automatically resend uncertain outcomes.
9. Provide a working opt-out reply address. The owner checks that mailbox daily and records requests in the suppression store. The HTA checks that store before every send. US business-to-business marketing is covered by CAN-SPAM.
10. Read all system-wide behavior from a validated INI: SMTP endpoint/auth identity/security flags and internal test recipient; Access .mdb path/provider/bitness; from/reply address; minimum queue interval; send mode; display time zone; template root and image policy; opt-out review cadence; and business postal address. Store campaign-specific settings, template and image versions, contacts, suppressions, queue state, and opt-out review status in the .mdb. Store the SMTP password as a DPAPI-protected value in the .mdb, configured through a setup action. No operational value is hard-coded.
11. Define when settings take effect: transport and queue settings are revalidated before each in-app dispatch; a changed interval cannot shorten a gap already reserved; sender identity, postal address, and selected template/image version are frozen when a campaign is approved; invalid or incomplete settings block approval or sending. Configuration changes must not silently start or resume a campaign.
12. Before the HTA starts, verify the requested 32-bit/64-bit process architecture, matching Access OLE DB provider, ability to open the configured .mdb, and schema version. If any check fails, show a specific error and do not open the sending UI. Recheck the connection before dispatch after any database error.

Nonfunctional requirements

• Security: No plaintext mail credentials or access tokens in the INI, CSV, template, log, or source code. Restrict local data to the operator account; use DPAPI CurrentUser to protect the password in the database.
• Reliability: Durable state transition before an attempt, single active HTA instance, recoverable restart, no catch-up burst, and auditable ambiguity.
• HTML safety: Treat imported contact fields, template HTML, and image paths as untrusted input. Use an allowed HTML subset and a preview that cannot execute scripts or active content inside the privileged HTA. Accept only supported image types and template-relative paths inside the selected template folder.
• Privacy: Minimize stored personal data; redact addresses in diagnostic logs where possible; define retention and backup policy before deployment.
• Operability: Visible queue state, next eligible send time, last error, pause control, exportable report, and instructions for reopening and explicitly resuming the HTA.
• Portability: Confirm target Windows versions, HTA/WSH policy, provider authentication, and any database/driver installation on the actual machine.
• Deliverability: Validate sender domain authentication and SMTP provider marketing policy and sending limits before live rollout; do not treat a five-minute gap as a guarantee of inbox placement or policy compliance. If this server is Exchange Online, Microsoft's published guidance favors a specialist provider for bulk commercial email.

Stories and acceptance criteria

ID	Priority	User story	Acceptance criteria / independent demo
S1	P1	As the owner, I can import business contacts so I can prepare a campaign.	Given a CSV with valid, invalid, and duplicate rows, preview counts and reasons; commit only valid unique contacts with source and import time.
S2	P1	As the owner, I can suppress an address so it receives no more marketing.	Given an address is suppressed before dispatch, every queued campaign skips it; importing it again does not unsuppress it.
S3	P1	As the owner, I can import, select, and preview reusable HTML templates so I know what a recipient will see.	Imported .html files appear in a template library; a safe preview includes required sender/opt-out details; active content and missing required fields block approval; approving a campaign freezes its selected version.
S4	P1	As the owner, I can test and approve a campaign so live sends are intentional.	Test send targets only an approved internal address; campaign starts only after review of recipient count and final template.
S5	P1	As the owner, I can schedule sends so contacts receive messages at the chosen pace.	At most one attempted recipient per interval across campaigns while the HTA is open; reopening does not cause a burst or auto-resume.
S6	P1	As the owner, I can pause or cancel a campaign so no further sends start.	After pause/cancel is committed, a new attempt does not begin; in-flight provider response is still recorded.
S7	P1	As the owner, I can see outcomes so I can fix failures.	Accepted, failed, and uncertain are distinct; report shows attempts and provider identifiers without exposing credentials.
S8	P1	As the owner, I can reconcile uncertain attempts so retries do not create avoidable duplicates.	Sender stops automatic retry on an ambiguous response; operator may mark verified sent or explicitly authorize one retry.
S9	P1	As a recipient, I can opt out so I receive no further marketing.	Every campaign names the monitored reply mailbox; the owner can record a request during the daily review; once recorded, all queued campaigns honor it before another attempt.
S10	P2	As the owner, I can receive bounce/complaint events so bad addresses are removed promptly.	A hard bounce or complaint suppresses the address before another campaign can send; duplicate events are harmless.
S11	P2	As the owner, I can personalize messages so each business sees relevant content.	Unknown merge fields and empty required values fail preflight; HTML values are escaped.
S12	P2	As the owner, I can export reports so I can review campaign results.	CSV export includes campaign, recipient, attempt time, provider result, and suppression reason.
S13	P1	As the owner, I can change system-wide settings without editing code.	The app loads the documented INI keys for SMTP, Access provider/path/bitness, pacing, open-window send mode, template/image policy, reply address, review cadence, and postal address; invalid values block startup, approval, or sending with a clear error; password rotation stores only protected bytes in the .mdb.
S14	P1	As the owner, I can use local images in an HTML template so my design appears in the email.	Import resolves supported template-relative images, snapshots their bytes, previews them, and sends them as inline MIME resources referenced by cid: URLs; changing or deleting source images after approval does not change queued mail.
S15	P1	As the owner, I get a clear database-driver check before the app opens so I can fix a 32-bit/64-bit mismatch.	A launcher tests the configured provider in the selected architecture, opens the real .mdb, checks schema version, and starts the HTA only on success; a missing or wrong-bitness provider produces an actionable error.

Sprint outline

• Sprint 0, feasibility: Confirm SMTP/TLS/auth and inline-image MIME compatibility, provider size limits, 32-bit HTA/Access connectivity, .mdb schema creation, and a safe test mailbox. Exit: one internal test message with an embedded image through the proposed adapter and a successful startup gate on the target PC.
• Sprint 1, safe campaign creation: S1-S4, S9's opt-out intake, S13-S15. Exit: import to reviewed test send through validated configuration and Access .mdb storage, with an inline image and verified suppression path.
• Sprint 2, reliable in-app scheduling: S5-S8. Exit: close/reopen, pacing, single-instance, crash, and pause tests pass with a fake provider.
• Sprint 3, feedback and rollout: S10-S12, deployment notes, backup/restore drill, limited pilot, and provider feedback validation.

Sprint lengths and estimates should be set after the provider and deployment constraints are known.

Marketing source notes

• FTC guidance says CAN-SPAM applies to B2B commercial email, including truthful headers/subjects, identification as an ad, a physical postal address, an opt-out method, and honoring opt-outs: https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business
• Exchange Online recommends specialist providers for bulk commercial email: https://learn.microsoft.com/en-us/office365/servicedescriptions/exchange-online-service-description/exchange-online-limits