# FECA Mailshots Plugin

WordPress plugin project for defining, previewing, testing, and running mailshots using:

- data-source definitions stored in a mailshots database,
- recipient/source reads from a separate members database,
- per-user SMTP/IMAP credentials for send and sent-copy behavior.

## Repository Overview

- `feca_mailshots_plugin/`: plugin source code.
- `requirements/`: project requirements/specifications.
- `tests/`: integration/unit/fixture tests.
- `scripts/`: local helper scripts (deploy, tunnel, fixture server).
- `credentials/`: local development credentials (ignored in Git).
- `results/`: implementation notes and investigation outputs.

## Key Features

- WordPress admin navigation under `FECA Mailshots`.
- CRUD admin pages for:
  - Mailshots
  - Data Sources
  - Attachments
  - PDF Assets
- Profile page for per-user SMTP/IMAP credentials with explicit connection tests.
- Setup page for environment DB connection settings (admin-only).
- Mailshot Test and Run pages for render/send execution.
- DSL-based data source model with validation and preview.
- REST and admin-post APIs for data source operations.

## Runtime Data Routing

As defined in `requirements/environment.md`:

- **Write-path** tables (mailshot definitions/assets/run data): `MAILSHOTS_REMOTE_MYSQL_DB`
- **Read-path** recipient/source data: `MEMBERS_REMOTE_MYSQL_DB`

## Local Setup

1. Copy env template:
   - `cp credentials/.env.example credentials/.env`
2. Populate real values in `credentials/.env`.
3. Start MySQL tunnel (if required):
   - `scripts/mysql_tunnel.sh start`
4. (Optional) run fixture server:
   - `scripts/run_fixture_server.sh start`

## Testing

Examples:

- `php tests/integration/test_phase2_db_access.php`
- `php tests/integration/test_phase3_admin_crud_ui.php`
- `php tests/integration/test_phase3_db_access.php`
- `php tests/integration/test_phase4_run_flow.php`
- `php tests/integration/test_per_user_credentials.php`

## Deployment

- Deploy script: `scripts/deploy_remote.sh`
- Supports dry run:
  - `scripts/deploy_remote.sh --dry-run`
- Deployment script bumps plugin patch version automatically before real deploy.

## Security Notes

- Do not commit secrets.
- `credentials/.env` and key material are ignored by `.gitignore`.
- Per-user mail credentials are stored encrypted in the mailshots DB.

## Mail Sending Notes

- Mailshots send through WordPress's `wp_mail()`/PHPMailer service, configured with the current user's saved SMTP credentials for each send.
- SMTP EHLO uses the domain from the configured From email address.
- Standard message headers and MIME formatting are generated by WordPress/PHPMailer.
- BCC recipients are delivered through PHPMailer recipient handling and are not rendered into the message headers.
- Generated in-memory attachments, including rendered PDFs, are added to PHPMailer as string attachments.

## Important References

- Environment baseline: `requirements/environment.md`
- Mailshot requirements: `requirements/mailshot.md`
- Data source requirements: `requirements/mailshot_data_source.md`