=== SMTP (by ROBOTSTXT) Newsletter ===
Contributors: robotstxt
Tags: newsletter, smtp, email, bulk, queue, worker, amazonses, statistics
Requires at least: 4.7
Tested up to: 6.9
Requires PHP: 7.2
Stable tag: 2.2.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Integrates ROBOTSTXT SMTP configuration with Newsletter plugin for reliable bulk email delivery with database-backed queue and external workers.

== Description ==

SMTP (by ROBOTSTXT) Newsletter connects your Newsletter plugin with ROBOTSTXT SMTP and Amazon SES plugins, providing **reliable, scalable bulk email delivery** through a database-backed queue system with external worker processes.

= Key Features =

* **Database Queue**: Persistent email queue survives server restarts and crashes
* **External Workers**: CLI worker script for asynchronous processing independent of WordPress cron
* **Parallel Processing**: Run multiple workers simultaneously for high-volume campaigns
* **Automatic Retry**: Failed emails retry up to 3 times with exponential backoff
* **Real-Time Statistics**: Monitor queue status and campaign performance
* **Campaign Metrics**: Track speed, duration, success rate for each campaign
* **Amazon SES Support**: Native integration with Amazon SES API
* **Rate Limiting**: Respects ROBOTSTXT SMTP rate limits
* **Scalable**: Handle campaigns of any size with parallel workers

= Architecture =

**Version 2.2.0 introduces a queue-based architecture:**

* Newsletter campaigns are queued to database instead of sent immediately
* External worker processes pick up queued emails and send them via wp_mail()
* Statistics are tracked and preserved even after queue cleanup
* Multiple workers can run in parallel for high-volume sending

= Performance & Reliability =

**Reliability:**
* Emails persisted to database - no data loss on crashes
* Automatic retry with exponential backoff (5min → 15min → 30min)
* Stale lock recovery prevents stuck emails

**Scalability:**
* Support for 10+ parallel workers
* Process 10,000+ emails per hour with proper worker setup
* Campaign statistics track actual sending speed

**Monitoring:**
* Real-time queue status (pending, processing, sent, failed)
* Campaign metrics (start time, duration, speed, success rate)
* Detailed email queue view in admin

= Requirements =

* Newsletter plugin 9.0.0 or higher
* ROBOTSTXT SMTP plugin 2.0.0 or higher
* (Optional) ROBOTSTXT SMTP Amazon SES plugin 1.0.0 or higher
* CLI access for worker setup (cron or process supervisor)

= Setup =

**Installation:**
1. Install and activate the plugin
2. Go to Newsletter → SMTP (by ROBOTSTXT)
3. Enable integration and configure batch size

**Worker Setup (Required):**
Set up a cron job or process supervisor to run the worker:

Single worker:
`* * * * * php /path/to/wp-content/plugins/robotstxt-smtp-newsletter/worker.php "w1"`

Parallel processing (10 workers):
`* * * * * seq 1 10 | xargs -P10 -I{} php /path/to/worker.php "w{}"`

Workers read the Batch Size directly from the plugin settings database. With 10 parallel workers each picking up N emails, the total simultaneous throughput is 10 × N emails.

**For WordPress MultiSite:**
Workers require the --url parameter to specify which site to process:

`* * * * * php /path/to/worker.php "w1" --url="https://site.example.com"`

See Settings → SMTP → Queue Worker Configuration for detailed commands tailored to your installation.

= Monitoring =

Access statistics via:
* **Newsletter → SMTP (by ROBOTSTXT)** - Queue status and recent campaigns
* **Newsletter → Email Queue** - View all queued and sent emails
* **Newsletter → Statistics** - Detailed campaign performance metrics

= Recommended Settings =

**For Standard SMTP Providers (SendGrid, Mailgun, etc.):**
* Batch Size: 10-20
* Max Per Connection: 50-100

**For Amazon SES:**
* Batch Size: 50

**For Gmail/Outlook:**
* Batch Size: 5
* Max Per Connection: 20

== Installation ==

1. Install and activate Newsletter plugin
2. Install and activate ROBOTSTXT SMTP plugin
3. Configure SMTP settings in ROBOTSTXT SMTP
4. Upload this plugin to `/wp-content/plugins/`
5. Activate the plugin through the 'Plugins' menu
6. Go to Newsletter → ROBOTSTXT SMTP to configure

== Frequently Asked Questions ==

= Do I need to configure SMTP settings? =

No. The plugin uses the SMTP configuration from ROBOTSTXT SMTP plugin.

= Does this work with Amazon SES? =

Yes! If you have ROBOTSTXT SMTP Amazon SES plugin active, this plugin will automatically use SES API for even better performance.

= Will this work with my current Newsletter campaigns? =

Yes. This plugin seamlessly integrates with Newsletter's sending engine. Your existing campaigns will automatically benefit from improved performance.

= What is SMTPKeepAlive? =

SMTPKeepAlive is a PHPMailer feature that keeps the SMTP connection open between emails. Instead of connecting for each email, one connection is used for multiple emails, dramatically improving speed.

= How much faster is this compared to default Newsletter sending? =

In typical scenarios, you'll see 20-30x performance improvement. For example:
* 10,000 emails: From 8-10 hours to 35 minutes
* 50,000 emails: From 2 days to 3 hours

= Does this respect rate limits? =

Yes. The plugin integrates with ROBOTSTXT SMTP rate limiting system to ensure you don't exceed your provider's limits.

= Is the Redirection plugin compatible? =

A possible incompatibility with the Redirection plugin is currently under investigation. When Redirection is active in a MultiSite environment, it may issue HTTP redirect headers during WordPress initialization, which can interfere with CLI worker processes. The worker uses output buffering to mitigate known symptoms. If you experience issues with the worker on a site running the Redirection plugin, please report them at the support link below.

== Changelog ==

= 2.2.8 =
* CHANGED: Batch Size is now read from plugin settings database — no longer passed as a command-line argument to the worker
* CHANGED: Worker command simplified to: php worker.php "w1" (no batch_size argument needed)
* IMPROVED: Batch Size field shows a throughput table: 10 workers × N emails = simultaneous emails
* IMPROVED: Worker section displays the current calculated simultaneous email count
* TECHNICAL: Legacy format (php worker.php 10 "w1") still supported with a deprecation warning

= 2.2.7 =
* IMPROVED: Worker now runs as a continuous loop, draining the queue completely before exiting
* IMPROVED: Statistics are synced after each batch
* IMPROVED: Worker output includes worker ID on each line for clearer parallel logs
* FIXED: Uneven work distribution between parallel workers

= 2.2.6 =
* CRITICAL FIX: Worker now suppresses plugin header warnings in MultiSite environments
* CRITICAL FIX: Fixed Newsletter base class dependencies not loading in DOING_CRON context
* CRITICAL FIX: Worker now manually initializes plugin when newsletter_loaded hook doesn't fire
* CRITICAL FIX: Fixed MultiSite subdirectory site detection - worker now correctly loads site from --url path
* CRITICAL FIX: Removed WP_CLI constant - caused fatal errors with multisite-clone-duplicator and similar plugins
* FIXED: "headers already sent" warnings from Redirection plugin and other plugins
* IMPROVED: Output buffering prevents header warnings from breaking worker execution
* IMPROVED: Worker loads NewsletterAddon and NewsletterMailerAddon before plugin
* IMPROVED: Worker calls Plugin::instance_init() manually for proper initialization
* IMPROVED: REQUEST_URI now parsed from URL path for correct MultiSite site selection

= 2.2.5 =
* CRITICAL FIX: Worker now loads plugin manually in DOING_CRON context
* FIXED: "Newsletter SMTP plugin is not active" error in worker script
* IMPROVED: Worker compatibility with all WordPress environments including MultiSite

= 2.2.4 =
* CRITICAL FIX: Speed calculation now uses actual NEWSLETTER_CRON_INTERVAL value
* FIXED: Batch_size was being divided by 5 due to incorrect cron interval assumption
* IMPROVED: Plugin now dynamically calculates speed based on actual Newsletter cron interval
* IMPROVED: Supports any cron interval (60s, 300s, etc.) without hardcoded assumptions

= 2.2.3 =
* CRITICAL FIX: Overridden get_emails_per_run() to bypass Newsletter's internal calculation
* FIXED: Newsletter was calculating batch = speed / 12, resulting in only 8-16 emails per execution
* FIXED: Plugin now directly returns configured batch_size for proper queue loading

= 2.2.2 =
* FIXED: Newsletter now correctly respects configured batch_size when enqueuing emails
* FIXED: Emails are now enqueued all at once to database instead of gradually
* IMPROVED: Added public $batch property that Newsletter reads directly
* IMPROVED: Added get_batch_size() method for Newsletter compatibility

= 2.2.1 =
* NEW: MultiSite detection in settings page with tailored worker commands
* NEW: Worker script now supports --url parameter for MultiSite environments
* IMPROVED: Settings page automatically displays installation-specific worker setup instructions
* IMPROVED: Worker documentation with MultiSite usage examples
* IMPROVED: README with dedicated MultiSite Installations section

= 2.2.0 =
* MAJOR: Database-backed email queue for persistent, reliable email delivery
* MAJOR: External CLI worker script for asynchronous email processing
* NEW: Queue Status widget with real-time statistics (pending, processing, sent, failed)
* NEW: Recent Campaigns section with key metrics in settings page
* NEW: Email Queue admin page to view all queued and sent emails
* NEW: Statistics admin page with campaign performance metrics
* NEW: Parallel worker support for high-volume sending (10+ workers simultaneously)
* NEW: Automatic retry with exponential backoff (up to 3 attempts: 5min → 15min → 30min)
* NEW: Campaign statistics tracking (start time, duration, speed, success rate)
* CHANGED: Emails are now queued to database instead of sent immediately
* CHANGED: Campaign statistics now grouped by unique Newsletter ID instead of campaign name
* REMOVED: max_per_connection setting (no longer needed with worker architecture)
* FIXED: Duplicate campaign statistics for campaigns with same name but different IDs
* BREAKING: Manual worker setup required - emails no longer send automatically

= 1.0.0 =
* Initial release
* SMTPKeepAlive support for SMTP
* Amazon SES API integration
* Batch processing
* Settings page in Newsletter admin
* Rate limiting integration

== Upgrade Notice ==

= 2.2.7 =
Workers now drain the full queue per invocation. Recommended upgrade for better parallel distribution.

= 2.2.6 =
CRITICAL: Fixed multiple worker issues in MultiSite environments including header warnings, class loading, and subdirectory site detection. Essential for reliable worker operation.

= 2.2.5 =
CRITICAL: Fixed worker script not loading plugin in DOING_CRON context. Essential for worker functionality.

= 2.2.4 =
CRITICAL: Fixed speed calculation to work with any Newsletter cron interval. Resolves batch_size division issues.

= 2.2.3 =
CRITICAL: Fixed Newsletter loading only 8-16 emails per execution. Now correctly loads all emails based on configured batch_size.

= 2.2.2 =
Fixed batch size enforcement - emails now enqueue correctly all at once instead of gradually.

= 2.2.1 =
Improved MultiSite support with automatic detection and tailored worker commands.

= 2.2.0 =
Major update with queue-based architecture. Manual worker setup required - see settings page for commands.

= 1.0.0 =
Initial release of SMTP (by ROBOTSTXT) Newsletter.