robotstxt-smtp-newsletter/readme.txt

=== 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.2
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 10 "w1"`

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

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

`* * * * * php /path/to/worker.php 10 "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.

== Changelog ==

= 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.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.