85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
# 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`
|