# CRD Email Agent — Version 1.0.9

A single-user, single-machine campaign agent that sends approved template sequences through one dedicated SMTP account, monitors its IMAP Inbox, stops follow-ups on replies, and returns uncertain conversations to a human.

## What this build does

- Stores campaigns, contacts, sequence steps, schedules, states and audit events in local SQLite.
- Configures follow-up delays in whole days from the preceding sequence step.
- Sends through the dedicated account's SMTP server.
- Supports standard mail accounts and webmail-hosted accounts when the provider exposes authenticated SMTP and IMAP services; it does not automate a webmail webpage.
- Sends multipart emails with a polished HTML layout and a plain-text fallback.
- Embeds an uploaded logo and signature image directly in each message, with optional signature text.
- Adds a visible mail-based opt-out link and `List-Unsubscribe` mailto header to every campaign email.
- Globally suppresses an address after an unsubscribe reply, cancels that address across all campaigns, and excludes it from future imports.
- Provides an in-app visual preview using the selected template, logo, signature and opt-out footer.
- Allows stopped or draft campaigns to be permanently deleted while retaining global opt-out protection.
- Makes overview metrics navigable and provides separate manual Inbox checking and due-email execution controls.
- Allows the local activity history to be permanently cleared without deleting campaigns, messages, replies, or opt-out suppressions.
- Includes an offline in-app Help guide for mailbox setup, AI connection, campaigns, replies, handoffs, and troubleshooting.
- Ships with a responsive dark graphite interface, lime operational accents, a persistent desktop sidebar, and compact navigation on smaller screens.
- Reads only the dedicated account's IMAP Inbox.
- Matches replies using `In-Reply-To`/`References`, with exact sender-address fallback.
- Cancels all pending follow-ups after a matched inbound reply.
- Requires a successful Inbox synchronization before sending anything due.
- Recalculates later follow-ups from each preceding email's actual send time, so shutdowns do not collapse several overdue steps into an immediate burst.
- Deterministically detects unsubscribe requests, common bounces and automatic/out-of-office responses.
- Optionally connects to an external OpenAI-compatible HTTPS API for reply classification, summaries, and the approval-controlled in-app AI Assistant.
- Keeps **Mailbox** and **External AI (Optional)** configuration separate. The complete self-managed email workflow continues without any AI connection.
- Lets the human write a reply, close the item, or email the available conversation to a colleague with an optional internal note. A handoff is marked complete only after SMTP delivery succeeds.
- Encrypts the mailbox password with Windows DPAPI. It can be decrypted only by the same Windows user on the same machine.

## Important limitations

- The app must be running and the machine must be awake and online.
- This version supports username/password or app-password SMTP and IMAP. It does not implement OAuth.
- Some mail services disable password authentication. Use a dedicated mailbox/server that explicitly supports SMTP and IMAP authentication, preferably with an app-specific password.
- The SQLite database is local but **not encrypted**. It contains campaign details and the text of matched replies. The mailbox password is separately DPAPI-encrypted.
- Sender-address fallback can be ambiguous if the same address participates in several active campaigns. Message headers take priority.
- Handoff emails contain the available stored conversation. Campaign emails sent before this upgrade may not have their original outbound body stored, so older handoff threads can be incomplete.
- The program does not establish that a campaign is lawful or that recipients consented. The user remains responsible for recipient authorization, suppression and applicable marketing rules.
- The standalone release is an unsigned portable Windows application, not a code-signed installer or unattended Windows service. Its private Python runtime is included; users do not install Python separately.

## Run

For the standalone release, use 64-bit Windows 10 or 11. Python is included privately in the package.

1. Extract the complete release ZIP, then double-click `Install CRD EMAIL AGENT for WIN.exe`.
2. The installer copies the application into the current user's local application folder and creates Desktop and Start-menu shortcuts. Administrator rights are not required.
3. The launcher stays in the Windows notification area while the agent is running. Double-click its tray icon to reopen the dashboard or right-click it to exit.
4. Open `http://127.0.0.1:8765` manually only if the browser does not open automatically.
5. Open **Connections setup → Connect mailbox** and configure the dedicated mailbox. External AI is optional and separate.
6. Test SMTP and IMAP before enabling automation.
7. Create a small test campaign addressed only to an account you control.

Developers can still run the unpackaged source with Python 3.11 or newer:

```powershell
python app.py
```

The app listens only on `127.0.0.1`; it is not exposed to other machines.

## Safe first test

1. Use two addresses you control: the dedicated agent mailbox and one recipient mailbox.
2. Create one initial message and one follow-up delayed by at least 1 day.
3. Confirm the initial message appears in the receiving mailbox.
4. Reply from the recipient mailbox.
5. Select **Check for messages**.
6. Confirm the reply appears in **Needs attention** and the follow-up is cancelled.

## External AI endpoint

The AI endpoint is optional. Without it, deterministic rules identify unsubscribe, bounce, automatic response, out-of-office and possible positive intent; everything else goes to human review.

External AI is optional. It requires separate API access, an HTTPS endpoint, exact model ID, and API key; a consumer chat subscription may not include API access. The provider must expose OpenAI-compatible `/v1/models` and `/v1/chat/completions` routes. The API key is encrypted with Windows DPAPI. When explicitly authorized, selected campaign and reply data is sent to the provider for classification or chat. The assistant may propose only checking messages, running due emails, or pausing/starting a campaign, and the app requires user approval before executing the proposal.

The in-app **? Help** guide explains these terms for first-time users, where they are normally found in a provider's official API/developer dashboard, the difference between a chat subscription and API access, possible separate billing, consent, key protection, testing, and the assistant's restricted authority.

It includes separate setup directions for OpenAI/ChatGPT, Anthropic/Claude, Google Gemini, and OpenRouter. Provider addresses are handled as complete OpenAI-compatible base URLs, including provider-specific paths.

## Tests

```powershell
python -m unittest discover -s tests -v
```
