0 Day Analytics – Mails Module Developer Documentation

The Mail Module provides comprehensive email monitoring, logging, and SMTP configuration for WordPress sites. It intercepts all emails sent via wp_mail(), records them to a custom database table with full metadata, and provides a WP_List_Table-based admin UI for browsing, searching, and managing email history.

Key Capabilities

• Intercept and log all wp_mail() calls with full metadata (headers, attachments, backtrace)
• Record delivery status (success/failure) with error messages
• Capture CC, BCC, Reply-To headers and attachment details
• Measure email delivery time (microsecond precision)
• Auto-categorize emails (order, user, system, marketing, notification, transactional)
• Detect and flag time-sensitive emails as non-resendable
• Identify the originating plugin/theme via backtrace analysis
• Configure external SMTP providers (Gmail, SES, Mailgun, SendGrid, etc.)
• Compose and send new emails from the admin with rich-text editor
• Resend previously logged emails
• BuddyPress and Post SMTP plugin compatibility
• Auto-clear schedule via cron job
• Multisite support with per-site logging and filtering

Technology Stack

• PHP 7.4+ (strict types)
• WordPress WP_List_Table API
• WordPress wp-api-fetch for REST interactions
• PHPMailer (WordPress bundled) for SMTP delivery
• WordPress TinyMCE editor for email composition
• jQuery + Thickbox for detail modals

advanced-analytics/
├── classes/
│   └── vendor/
│       ├── controllers/
│       │   ├── class-wp-mail-log.php          — Email capture & logging engine
│       │   ├── class-mail-smtp-settings.php   — SMTP configuration & delivery
│       │   └── api/
│       │       └── class-endpoints.php        — REST API (mail body endpoint)
│       ├── entities/
│       │   └── class-wp-mail-entity.php       — Database schema & column definitions
│       ├── helpers/
│       │   └── class-ajax-helper.php          — AJAX endpoints (test email)
│       ├── lists/
│       │   ├── class-wp-mail-list.php         — WP_List_Table for mail log display
│       │   └── views/
│       │       └── class-wp-mail-view.php     — Page rendering, compose form, detail modal JS
│       └── settings/
│           └── settings-options/
│               └── mail-list.php              — Settings form fields (module + SMTP)
└──assets/
    ├── css/                                   — Stylesheets
    └── js/
        └── admin/
            └── aadvana-settings.js            — Test mail AJAX button handler

UI Components

• “Compose New” button in page header
• Filter views – All | Successful | Unsuccessful | HTML | Text | With attachments
• Plugin filter dropdown – filter by originating plugin
• Site filter dropdown – filter by blog ID (multisite only)
• Search box – full-text search across all columns (input name: s)
• Sortable columns – All admin columns are sortable
• Pagination – configurable via screen options (default: 20)
• Row actions – Details | Resend | Delete (per row)
• Bulk actions – Delete (for selected rows)

┌──────────────────────────────────────────────────────────────┐
│  WP Mail Log                                [Compose New]    │
│──────────────────────────────────────────────────────────────│
│  All (156) | Successful (148) | Failed (8) | HTML | Text     │
│  [Plugin ▼] [Site ▼]                       [🔍 Search]       │
│──────────────────────────────────────────────────────────────│
│  ☐ Date ↕   | To        | Subject    | Category | Status     │
│  ☐ Today    | user@..   | Welcome    | user     | ✓          │
│     Details | Resend | Delete                                │
│  ☐ Today    | admin@..  | Error log  | system   | ✓          │
│     Details | Delete                                         │
│  ☐ Yest.    | cust@..   | Order #12  | order    | ✗          │
│     Details | Delete                                         │
│──────────────────────────────────────────────────────────────│
│  Bulk Actions [▼] [Apply]              ‹ 1 of 8 ›            │
└──────────────────────────────────────────────────────────────┘

Form Fields

Settings Sections

1. Mail List Options – Enable module, auto-clear schedule
2. External SMTP Provider – Full SMTP configuration
3. Test Mail Delivery – Send test email button

The email capture engine. Hooks into WordPress and third-party mail systems to intercept, analyze, and log all outgoing emails.

Hook Registration (init method)

<?php
// Core WordPress hooks
\add_filter( 'wp_mail', [ self::class, 'record_mail' ], PHP_INT_MAX );
\add_action( 'wp_mail_failed', [ self::class, 'record_error' ] );
\add_filter( 'wp_mail_content_type', [ self::class, 'detect_content_type' ] );
\add_action( 'phpmailer_init', [ self::class, 'extract_more_mail_info' ], PHP_INT_MAX );

// BuddyPress hooks
\add_action( 'bp_send_email', [ self::class, 'bp_record_mail' ] );
\add_filter( 'bp_email_use_wp_mail', [ self::class, 'bp_mail_check' ] );
\add_action( 'bp_send_email_failure', [ self::class, 'bp_record_error' ] );

// Post SMTP plugin hooks
\add_action( 'post_smtp_on_success', [ self::class, 'post_smtp_extract_from' ] );
\add_action( 'post_smtp_on_failed', [ self::class, 'post_smtp_extract_from' ] );

Key Methods

Manages external SMTP provider configuration and email delivery routing.

Constants

<?php
public const NONCE_NAME = ADVAN_PREFIX . 'mail'; // 'aadvana_mail'

Key Methods

SMTP Delivery Flow

<?php
// Hooks at a very high priority to override other plugins
add_action( 'phpmailer_init', [ self::class, 'deliver_email_via_smtp' ], 999999 );

public static function deliver_email_via_smtp( $phpmailer ) {
    $settings = self::get_smtp_settings();
    
    // Validate before configuring
    if ( ! self::validate_smtp_settings( $settings ) ) {
        return;
    }

    $phpmailer->isSMTP();
    $phpmailer->Host       = $settings['smtp_host'];
    $phpmailer->Port       = $settings['smtp_port'];
    $phpmailer->SMTPSecure = $settings['encryption_type'];
    $phpmailer->SMTPAuth   = ! empty( $settings['smtp_username'] );
    $phpmailer->Username   = $settings['smtp_username'];
    $phpmailer->Password   = $settings['smtp_password'];
    
    // Optional From override
    if ( ! empty( $settings['from_email'] ) ) {
        $phpmailer->From     = $settings['from_email'];
        $phpmailer->FromName = $settings['from_email_name'];
    }
    
    // SSL bypass for development
    if ( $settings['smtp_bypass_ssl_verification'] ) {
        $phpmailer->SMTPOptions = [
            'ssl' => [
                'verify_peer'       => false,
                'verify_peer_name'  => false,
                'allow_self_signed' => true,
            ],
        ];
    }
}

Extends Abstract_List (which extends WP_List_Table). Handles the mail log admin list table rendering, column management, sorting, searching, filtering, and bulk operations.

Constants

<?php
const WP_MAIL_MENU_SLUG     = 'advan_wp_mail';
const PAGE_SLUG             = ADVAN_INNER_SLUG . '_page_advan_wp_mail';
const SCREEN_OPTIONS_SLUG   = 'advanced_analytics_wp_mail_list';
const SEARCH_INPUT          = 's';
const NEW_ACTION            = 'advan_mail_new';
const NONCE_NAME            = 'advana_wp_mail_manager';
const SITE_ID_FILTER_ACTION = 'filter_site_id';
const PLUGIN_FILTER_ACTION  = 'aadvana_page_advan_wp_mail_filter_plugin';

Key Methods

Handles page rendering for mail screens (list, compose) and includes inline JavaScript for the detail modal.

Key Methods

Detail Modal JavaScript

The view class injects inline JavaScript that:

• Intercepts “Details” link clicks
• Fetches mail details via REST API: /aadvana/v1/mail_body/{id}/
• Renders the email in a Thickbox modal with metadata table
• Provides copy-to-clipboard and Web Share API buttons
• Color-codes category badges
• Formats file sizes (bytes → KB → MB)
• Displays delivery time in milliseconds

Database entity class. Defines the mail log table schema, column definitions, and provides static methods for data access.

Table Name

<?php
$table_name = $wpdb->prefix . 'advan_wp_mail_log';

Key Methods

Mail log entries are stored in the {prefix}advan_wp_mail_log table:

Database Indexes

PRIMARY KEY (id)
KEY email_category (email_category)
KEY status (status)

Attachment JSON Format

[
  {
    "id": 123,
    "url": "https://example.com/wp-content/uploads/file.pdf",
    "src": "icon_url",
    "alt": "File name",
    "mime_type": "application/pdf"
  },
  {
    "id": -1,
    "url": "path/to/file.txt",
    "alt": "file.txt",
    "note": "Attachment not in media library"
  }
]

The following diagram shows the sequence of hooks and methods involved in capturing an email:

wp_mail() called
    │
    ├─ 1. wp_mail filter (PHP_INT_MAX) ──→ record_mail()
    │      ├── Extract: to, subject, message, headers, attachments
    │      ├── Parse headers → CC, BCC, Reply-To
    │      ├── Backtrace analysis → identify originating plugin
    │      ├── categorize_email() → detect category
    │      ├── can_resend_email() → check time-sensitivity
    │      ├── get_attachment_locations() → resolve file details
    │      ├── calculate_attachment_stats() → count + sizes
    │      └── INSERT into advan_wp_mail_log
    │
    ├─ 2. wp_mail_content_type filter ──→ detect_content_type()
    │      └── Store is_html flag
    │
    ├─ 3. phpmailer_init action (PHP_INT_MAX) ──→ extract_more_mail_info()
    │      ├── Access PHPMailer properties via closure
    │      ├── Extract: From, FromName, To, Subject, Body, ContentType
    │      ├── Extract: Attachment array, MailHeader
    │      ├── Calculate delivery time (microtime delta)
    │      └── UPDATE existing log entry with enriched data
    │
    └─ 4. wp_mail_failed action ──→ record_error()
           └── UPDATE status=0, store error message

Emails are auto-categorized based on keyword detection in the subject and message body. The system checks in priority order, returning the first match:

The module includes a safety mechanism to prevent resending time-sensitive emails.

Time-Sensitive Keywords (prevent resend)

<?php
$blocked_keywords = [
    'password reset',  'verification code',
    'verify your',     'confirm your',
    'one-time',        'expires',
    'expiring',        '2fa',
    'two-factor',      'authentication code',
    'otp',
];

Resend Flow

The handler reconstructs the original email from stored data:

1. Retrieves mail record from database by ID
2. Rebuilds headers array from stored CC, BCC, Reply-To
3. Restores attachment paths
4. Calls wp_mail() with all original parameters
5. The re-sent email is automatically logged as a new entry

Send Test Email AJAX

Implementation Details

• Validates nonce and capability
• Sanitizes the email address via sanitize_email()
• Selects a random fun test message from predefined templates
• Includes the site URL and current date/time in the test email body
• Sets Content-Type: text/html header
• Sends via wp_mail() which routes through SMTP if configured
• Returns JSON success/error response

JavaScript Example

jQuery(document).on('click', '#mail_send_test_ajax', function(e) {
    e.preventDefault();
    
    var email = jQuery('#test_email_address').val();
    
    jQuery.ajax({
        url: ajaxurl,
        type: 'POST',
        data: {
            action: 'aadvana_send_test_email',
            email: email,
            _wpnonce: aadvana_settings.nonce
        },
        success: function(response) {
            if (response.success) {
                alert('Test email sent successfully!');
            } else {
                alert('Failed: ' + response.data);
            }
        }
    });
});

Get Mail Body GET

Success Response

{
    "success": true,
    "mail_body": "<html>...full email content...</html>",
    "email_to": "[email protected]",
    "email_from": "[email protected]",
    "email_cc": "[email protected]",
    "email_bcc": "[email protected]",
    "email_reply_to": "[email protected]",
    "subject": "Welcome to our site",
    "email_category": "user",
    "additional_headers": "{\"Content-Type\": \"text/html\"}",
    "message_size": 2048,
    "message_size_formatted": "2 KB",
    "total_size": 15360,
    "total_size_formatted": "15 KB",
    "attachment_count": 1,
    "attachment_total_size": 13312,
    "attachment_total_size_formatted": "13 KB",
    "delivery_time": 0.125,
    "can_resend": 1,
    "attachments": "<ul>...attachment HTML...</ul>"
}

Error Response

{
    "code": "empty_row",
    "message": "No record found.",
    "data": {
        "status": 400
    }
}

cURL Example

curl -X GET \
  "https://example.com/wp-json/aadvana/v1/mail_body/42/" \
  -H "X-WP-Nonce: <nonce>" \
  --cookie "wordpress_logged_in_xxx=..."

JavaScript (wp-api-fetch) Example

wp.apiFetch({
    path: '/aadvana/v1/mail_body/42/',
}).then(response => {
    if (response.success) {
        console.log('Subject:', response.subject);
        console.log('Category:', response.email_category);
        console.log('Delivery time:', response.delivery_time, 'sec');
    }
}).catch(err => {
    console.error('Failed to fetch mail body:', err.message);
});

Filters Used FILTER

Actions Used ACTION

The SMTP implementation uses WordPress’s bundled PHPMailer library. When SMTP settings are configured and the module is enabled, the plugin hooks into phpmailer_init at priority 999999 (intentionally very high to override other plugins).

Configuration Hierarchy

wp_mail() called
    │
    └─ phpmailer_init action fires
           │
           ├─ Priority 10-999998: Other plugins' PHPMailer hooks
           │
           ├─ Priority 999999: Mail_SMTP_Settings::deliver_email_via_smtp()
           │     ├── Validate settings (host + port required)
           │     ├── Set isSMTP() mode
           │     ├── Configure Host, Port, Auth, Encryption
           │     ├── Set custom XMailer header
           │     ├── Override From/FromName (if configured)
           │     └── Apply SSL bypass (if enabled)
           │
           └─ Priority PHP_INT_MAX: WP_Mail_Log::extract_more_mail_info()
                 └── Extract enriched data for logging

WordPress Options (SMTP)

Settings are rendered using the plugin’s Settings::build_option() builder. The mail settings are on the Mail Options tab within the main settings page.

<?php
// Check if mail module is enabled
$enabled = Settings::get_option( 'wp_mail_module_enabled' );

// Get the auto-clear schedule
$schedule = Settings::get_option( 'advana_mail_logging_clear' );

// Get SMTP configuration
$smtp_host = Settings::get_option( 'smtp_host' );
$smtp_port = Settings::get_option( 'smtp_port' );

// Check SMTP encryption type
$encryption = Settings::get_option( 'encryption_type' );

Auto-Clear Cron Job

<?php
// Hook name for the auto-clear cron
$hook = 'aadvana_mail_logging_clear';

// Callback
add_action( 'aadvana_mail_logging_clear', [
    WP_Mail_List::class,
    'truncate_wp_mail_table'
]);

Columns

Filter Views

Search

The search box performs full-text search across all columns. Input parameter: s.

Row Actions (per mail entry)

Bulk Actions

Security

• Nonce verification for all form submissions
• Capability check: manage_options required
• Resend nonce: resend_email_{id} (unique per entry)

BuddyPress

Full support via dedicated hooks:

• bp_send_email — Captures BuddyPress emails before they’re routed
• bp_email_use_wp_mail — Checks if BuddyPress falls back to wp_mail()
• bp_send_email_failure — Logs BuddyPress email failures

Post SMTP

Compatibility hooks for the Post SMTP plugin:

• post_smtp_on_success — Extracts “From” address after successful Post SMTP delivery
• post_smtp_on_failed — Extracts “From” address after Post SMTP failures

WooCommerce

WooCommerce emails sent via wp_mail() are automatically captured and categorized as order based on keyword detection in the subject/body.

Example 1: Check if Mail Module is Enabled

<?php
use ADVAN\Helpers\Settings;

$mail_enabled = Settings::get_option( 'wp_mail_module_enabled' );

if ( $mail_enabled ) {
    // Mail module is active — emails are being logged
}

Example 2: Fetch a Mail Record via REST API (PHP)

<?php
// Programmatic REST API call within WordPress
$request = new \WP_REST_Request( 'GET', '/aadvana/v1/mail_body/42/' );
$response = rest_do_request( $request );

if ( ! $response->is_error() ) {
    $data = $response->get_data();
    error_log( 'Email subject: ' . $data['subject'] );
    error_log( 'Delivery time: ' . $data['delivery_time'] . 's' );
    error_log( 'Category: ' . $data['email_category'] );
}

Example 3: Query Mail Log Entries Directly

<?php
use ADVAN\Entities\WP_Mail_Entity;

// Get all failed emails from the last 24 hours
$failed_mails = WP_Mail_Entity::get_items([
    'status'   => 0,
    'per_page' => 50,
    'orderby'  => 'time',
    'order'    => 'DESC',
]);

foreach ( $failed_mails as $mail ) {
    printf(
        "To: %s | Subject: %s | Error: %s\n",
        $mail['email_to'],
        $mail['subject'],
        $mail['error']
    );
}

Example 4: Send Test Email via AJAX (JavaScript)

const formData = new FormData();
formData.append('action', 'aadvana_send_test_email');
formData.append('email', '[email protected]');
formData.append('_wpnonce', aadvana_settings.nonce);

fetch(ajaxurl, {
    method: 'POST',
    body: formData,
})
.then(r => r.json())
.then(data => {
    if (data.success) {
        console.log('Test email sent!');
    } else {
        console.error('Send failed:', data.data);
    }
});

Example 5: Access SMTP Settings Programmatically

<?php
use ADVAN\Controllers\Mail_SMTP_Settings;

$settings = Mail_SMTP_Settings::get_smtp_settings();

if ( ! empty( $settings['smtp_host'] ) ) {
    error_log( sprintf(
        'SMTP configured: %s:%d (%s)',
        $settings['smtp_host'],
        $settings['smtp_port'],
        $settings['encryption_type'] ?: 'none'
    ));
}

Example 6: Multisite – Filter Emails by Site

<?php
use ADVAN\Entities\WP_Mail_Entity;

// Get emails for blog ID 3
$site_emails = WP_Mail_Entity::get_items([
    'blog_id'  => 3,
    'per_page' => 25,
]);

echo count( $site_emails ) . ' emails from site #3';