WPCalibrate Mail Delivery

Enterprise-grade email delivery, multi-connection routing, API transports, SMTP reliability, automatic fallback failover, retry queue, and logging for WordPress & WooCommerce.

📖 About WPCalibrate Mail Delivery

Transactional emails are the lifeblood of WordPress and WooCommerce sites: password resets, order confirmations, invoice receipts, shipping tracking, and customer notifications. Default server wp_mail() often suffers from silent delivery failures, shared hosting rate-limits, and missing delivery visibility.

WPCalibrate Mail Delivery completely transforms your site's email infrastructure. Built on modern PHP 8.2+ strict-typing standards and modular enterprise architecture, it intercepts outgoing emails, routes them through authenticated cloud providers or high-speed SMTP relays, logs delivery outcomes with zero-privacy leakage, and automatically fails over to backup providers if your primary gateway is unreachable.

Key Architectural Pillars

• Zero-Dependency PSR Autoloading: Clean, PSR-4 compliant namespace architecture with no bloated external vendor directories.
• Failover-First Pipeline: Decoupled transport layer that catches transient provider outages and fails over without dropping critical order emails.
• Authenticated AES-256-GCM Encryption: Passwords, API tokens, and private secrets are encrypted at rest with keys derived from WordPress security salts.
• Privacy by Default: Message bodies are not stored in the database unless explicitly activated by an administrator.
• High-Performance Order Storage (HPOS): Officially declared compatible with WooCommerce HPOS and checkout block workflows.

✨ Features

🚀 Supported Mail Transports & API Providers

1. Generic SMTP: Secure PHPMailer transport with STARTTLS, SSL/TLS, and connection handshake diagnostics.
2. Google Workspace / Gmail: Official REST API transport via OAuth 2.0 with automatic token refresh.
3. Microsoft 365 / Outlook: Microsoft Graph API v1.0 integration using Azure AD OAuth 2.0.
4. Amazon SES: Cloud delivery via Amazon Simple Email Service using AWS Signature Version 4 (SigV4).
5. SendGrid: Official SendGrid Web API v3 with webhook delivery status tracking.
6. Mailgun: High-throughput REST API with US and EU regional endpoint selection and webhook HMAC verification.
7. Brevo (Sendinblue): Transactional email delivery via Brevo REST API v3.
8. Postmark: Fast, reliable transactional messaging via Postmark Server API.
9. MailerSend: Modern developer API transport with domain verification and status callbacks.
10. SMTP.com: High-volume delivery via SMTP.com API v4.
11. Local Sandbox Mailer: Zero-configuration local simulation mailer for safe testing without external credentials or open SMTP ports.
12. WordPress / PHP Mail: Built-in server fallback transport.

🛡️ Multi-Connection Routing & Intelligent Failover

• Primary & Secondary Routes: Assign dedicated providers as primary transmitters and secondary failover relays.
• Circuit-Breaker Recovery: When an API returns a 5xx or network timeout, the delivery engine automatically engages the backup route.
• Source-Based Routing: Route WooCommerce receipts through dedicated high-reputation transactional providers while sending routine administrative digests through bulk relays.

🔄 Resilient Retry Queue

• Action Scheduler Core: Integrates seamlessly with Action Scheduler for concurrent, background async processing, falling back to WP-Cron if Action Scheduler is inactive.
• Exponential Backoff: Configurable retry intervals (e.g., 1m, 5m, 15m, 1h, 6h) prevent server hammering during downstream provider incidents.
• Concurrency Locks: Transients-based execution mutex ensures retry batches never duplicate email deliveries.

📊 Privacy-Safe Delivery Logging

• Custom High-Performance DB Table: Dedicated indexing on status, connection_id, created_at, and woocommerce_email_id.
• Strict Privacy Mode: Email bodies are excluded by default to ensure GDPR and HIPAA compliance.
• Automated Retention Engine: Scheduled daily cron purges logs older than your specified threshold (7 to 365 days) in safe chunked batches.
• CSV Log Export: Export filtered delivery audits directly from the WordPress administration dashboard.

🧪 Diagnostics, Testing & One-Click Demo Mode

• Interactive Test Email Tool: Validate credentials, headers, and multipart HTML formatting instantly.
• Real-Time SMTP Handshake Tester: Tests socket connectivity, STARTTLS negotiation, and authentication in seconds.
• Sanitized System Diagnostics: One-click system report exports server runtime, PHP extensions, DNS records, and active transport health while strictly masking sensitive credentials.
• 1-Click Demo Data & Sandbox: Pre-seed simulated connections and sample logs for instantaneous evaluation and UI verification.

📡 Real-Time Delivery Webhooks

• Secure REST endpoints (/wp-json/wpcalibrate-mail/v1/webhook/{provider}) receive real-time events.
• Track Delivered, Bounced, and Complained / Spam events in real time.
• Built-in signature verification (SendGrid ECDSA, Mailgun HMAC-SHA256, Postmark tokens).

🛠️ Architecture & Workflow

flowchart TD
    A[wp_mail Call] --> B[TransportManager Filter]
    B --> C{Active Connection?}
    C -->|No| D[Native Fallback]
    C -->|Yes| E[Primary Provider Transport]
    E -->|Success| F[Log Success & Record Message ID]
    E -->|Transient Error| G{Fallback Configured?}
    G -->|Yes| H[Fallback Provider Transport]
    H -->|Success| F
    H -->|Failure| I[Enqueue in Retry Queue]
    G -->|No| I
    I --> J[Action Scheduler / WP-Cron Retry Worker]
    J -->|Max Retries Exceeded| K[Log Failed Status]

📦 Installation & Setup

Requirements

• WordPress: 6.8 or higher
• PHP: 8.2 or higher
• PHP Extensions: curl, json, openssl, mbstring

Manual Installation

1. Download the latest wpcalibrate-mail-delivery-1.0.0.zip release.
2. In your WordPress admin, navigate to Plugins > Add New > Upload Plugin.
3. Select the ZIP file and click Install Now.
4. Click Activate Plugin.

Configuration Steps

1. Navigate to WPCalibrate > Mail Delivery in your WordPress admin menu.
2. Under the Connections tab, click Add Connection.
3. Choose your preferred provider (e.g., SMTP, SendGrid, Amazon SES, or Sandbox).
4. Enter your connection credentials and click Save Connection.
5. Switch to Tools & Testing, and click Send Test Email to verify your setup.

🔒 Security & Encryption

• Authenticated At-Rest Encryption: All API keys, passwords, and client secrets are encrypted using AES-256-GCM before being written to the database.
• Cryptographic Key Derivation: Keys are derived from AUTH_KEY and SECURE_AUTH_KEY via hash_hkdf with custom domain separation salts.
• Form Masking: Admin forms render masked strings (••••••••••••abcd) to avoid displaying credentials in plain HTML.
• Access Control: All administrative views and REST API endpoints strictly enforce manage_options capability checks and nonce validation.

📋 Changelog

Version 1.0.0

• Initial Production Release.
• Full support for 12 email transports:
  • Generic SMTP (PHPMailer with STARTTLS/SSL)
  • Google Workspace / Gmail (OAuth 2.0)
  • Microsoft 365 / Outlook (Azure AD Graph API)
  • Amazon SES (SigV4)
  • SendGrid Web API v3
  • Mailgun REST API (US & EU)
  • Brevo REST API v3
  • Postmark Server API
  • MailerSend API
  • SMTP.com API v4
  • Local Sandbox Mailer (Zero-config local simulator)
  • WordPress PHP Mail fallback
• Primary and fallback multi-connection routing engine.
• Resilient retry queue with Action Scheduler and WP-Cron fallback.
• Dedicated high-performance database logging table with automated retention cleanup.
• Interactive test email sender and real-time SMTP socket handshake tester.
• WooCommerce HPOS compatibility declaration.
• Webhook endpoints for real-time delivery tracking and event deduplication.
• One-click demo data seeder and cleanup tool for testing without live credentials.

📄 License & Credits

Developed with ❤️ by WPCalibrate.

This software is released under the GNU General Public License v2.0 or later (GPL-2.0-or-later). See LICENSE for full details.