MassMailer/.specs/project/PROJECT.md

MassMailer: draft project brief

Vision

A Windows desktop tool for the owner's 9 x 12 postcard business to prepare and schedule individual marketing emails to business contacts. The owner can see exactly who is queued, stop a campaign, and review what the mail provider accepted.

Known requirements

• UI technology requested: HTA with VBScript/JScript.
• Message type: marketing for the postcard business.
• Audience: US businesses, using publicly listed email addresses. Store the source URL/reference and collection date for each contact; public listing alone is not an opt-in record.
• Transport: configurable SMTP. Initial settings are netsol-smtp-oxcs.hostingplatform.com:587, user/from danielcovington@postcardmojo.com, TLS required, STARTTLS required. Authentication uses a username and password. The password must not be shared in project files or chat.
• Pacing: configurable QUEUE_INTERVAL=300 seconds as the initial minimum gap between individual send attempts (nominally 12/hour or 288/day if sending continuously).
• Sending occurs only while the owner is using the HTA. Closing the app stops new sends and leaves the campaign paused until the owner explicitly resumes it.
• Expected list size: fewer than 500 business addresses.
• Sending window: no hour or weekday restriction while the HTA is open. Timestamps are stored in UTC and displayed in local time.
• Message authoring: reusable HTML templates with embedded local image files for v1. A campaign uses a frozen template and image snapshot once approved; personalization is a later enhancement.
• Opt-outs: danielcovington@postcardmojo.com is the monitored reply mailbox. The owner checks it daily and enters requests into the suppression list. The HTA checks that list before later sends.
• The owner confirms the SMTP provider permits this marketing use; connection and STARTTLS compatibility still need a technical check.
• Backend: an Access .mdb database via 32-bit Microsoft.ACE.OLEDB.12.0 on the current PC. The UI launcher must check process bitness and actually open the selected provider before starting the HTA. Current diagnostics passed .mdb create/write/read in 32-bit hosts and failed in 64-bit hosts.
• Configuration rule: system-wide settings are editable in a validated .ini file; campaign choices, approved template/image versions, contacts, suppressions, queue state, review status, and a protected SMTP password value are editable or managed through the .mdb. No operational value is compiled into the scripts.
• Current implementation: Access schema/startup checks, contact import and suppression, protected SMTP password setup, and an explicit one-message internal SMTP test. Campaign sending is not implemented yet.

Working assumptions to validate

1. One email means one message addressed to one recipient; no CC/BCC batching.
2. The configured gap is a minimum interval between all send attempts from the sending account, across campaigns and including retries. The HTA starts at most one send at a time. The interval should have a safe minimum that the provider permits.
3. There is no daily or weekly blackout window in v1. The HTA must be open to send. Store instants in UTC, show local time in the UI, and do not burst through missed slots after an outage or app closure.
4. Campaigns require a preflight review and explicit start action. Imports never start sending by themselves.
5. Every contact has a source record and can be suppressed. Once an opt-out is recorded, future marketing to that address must stop before the next dispatch.
6. The first deployment is a single Windows machine, one operator, and one HTA process. Multiuser and cloud hosting are later decisions.
7. The example INI leaves BUSINESS_POSTAL_ADDRESS blank; campaign approval must require the real business address.

Success measures for v1

• No recipient is sent after they are suppressed, and no address receives two attempts for the same campaign through ordinary restart/retry paths.
• Configured pacing is respected across normal sends and retries.
• A crash or reboot preserves campaign and delivery state, with uncertain outcomes visible for manual reconciliation.
• Closing the HTA starts no new sends; reopening it does not resume a campaign without an explicit owner action.
• The operator can import, review, test-send, schedule, pause, resume, and export an audit report without editing scripts.

At the initial five-minute gap, a campaign with 500 recipients needs at least 41 hours 35 minutes from first to last send if it runs continuously, before retries or provider delays. At the stated size of fewer than 500 contacts, a full-list run is slightly shorter. The configurable gap determines campaign lead time.

Open decisions

ID	Decision needed	Why it matters
D2	Verify that the supplied SMTP server supports mandatory STARTTLS on port 587 with username/password authentication	Determines whether a VBScript/JScript-compatible transport can safely connect.
D3	Confirm the installed .mdb path, selected provider, and 32-bit HTA launch path during deployment	The startup gate must open the real database from the same architecture as the app.
D4	Confirm actual campaign frequency during pilot	Helps tune reporting and backups; the design sizes for at most 500 recipients per campaign.

Resolved decisions: D1 is US-only publicly listed business addresses; D5 is a configurable account-wide minimum gap while the app is open, with no catch-up bursts; D6 is reusable HTML templates with embedded local images; D7 is danielcovington@postcardmojo.com as the owner-monitored reply mailbox checked daily. The owner confirms SMTP marketing use is permitted and that sending stops when the HTA closes.

Source notes

• US commercial email rules also cover business-to-business mail: https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business
• UK business email rules vary by the type of business contact: https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/business-to-business-marketing/