first commit

README.md

@@ -0,0 +1,93 @@
+# Phishtest
+
+A phishing email testing tool designed to test Proofpoint TAP (Targeted Attack Protection) systems. Sends test phishing emails via SMTP2GO.
+
+## Setup
+
+1. Create and activate virtual environment:
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate
+   ```
+
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Configure environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your SMTP2GO API key and sender settings
+   ```
+
+## Usage
+
+### List available templates
+```bash
+python -m src.main list-templates
+```
+
+### Preview a template
+```bash
+python -m src.main preview --template password-reset --name "John Doe" --email "john@example.com"
+```
+
+### Send to a single recipient
+```bash
+python -m src.main send --template password-reset --to user@example.com --name "Test User"
+```
+
+### Send to multiple recipients from CSV
+```bash
+python -m src.main send --template password-reset --csv recipients.csv
+```
+
+### Dry run (preview without sending)
+```bash
+python -m src.main send --template password-reset --csv recipients.csv --dry-run
+```
+
+## Creating Templates
+
+Templates are stored in `templates/<template-name>/` with three files:
+
+- `metadata.json` - Subject line and sender name
+- `template.html` - HTML email body
+- `template.txt` - Plain text email body
+
+### Available template variables
+
+- `{{recipient_name}}` - Recipient's name
+- `{{recipient_email}}` - Recipient's email address
+- `{{company_name}}` - Company name from config
+- `{{date}}` - Current date
+
+### Example metadata.json
+```json
+{
+  "subject": "Password Reset Required",
+  "sender_name": "IT Security Team"
+}
+```
+
+## CSV Format
+
+Recipients CSV must have an `email` column. The `name` column is optional.
+
+```csv
+email,name
+john.doe@example.com,John Doe
+jane.smith@example.com,Jane Smith
+```
+
+## Configuration
+
+Set these in `.env` or as environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| SMTP2GO_API_KEY | Yes | Your SMTP2GO API key |
+| SENDER_EMAIL | Yes | Sender email address (must be verified in SMTP2GO) |
+| SENDER_NAME | No | Default sender display name |
+| COMPANY_NAME | No | Company name for templates |