feca-mailshots-plugin/README.md

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.

Important References

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