Asynchronous Transactional Emails & SMTP Timeouts: Routing WooCommerce Notifications Through Action Scheduler Under HPOS

Illustration of a high-speed WooCommerce checkout pipeline offloading synchronous SMTP handshakes and DOMPDF invoice rendering into an asynchronous Action Scheduler worker queue.

A WooCommerce checkout request has one job: validate the cart, take payment, write the order, and return JSON. When the same request also performs an SMTP handshake, waits on a relay, and renders a PDF invoice with DOMPDF or TCPDF before it answers, the response time of POST /?wc-ajax=checkout grows by 3 to 40 seconds. The customer sees a stalled WooCommerce checkout loading spinner, clicks "Place order" a second time, and your payment gateway either times out or creates a duplicate attempt. Meanwhile the PHP-FPM worker that handled the request stays pinned for the entire SMTP conversation, which is how a slow mail relay turns into a pool-wide stall during a traffic spike. In the worst case the order is written, the email is not, and support tickets start arriving with "I never got a confirmation." DOMPDF synchronous invoice rendering can further increase WooCommerce checkout latency when PDF invoice plugins generate attachments during the same PHP request. HTML-to-PDF conversion, font processing, and document generation consume additional CPU and memory before the transactional email can be delivered, increasing the risk of PHP execution timeouts.

The standard advice is a one-line filter. That advice is incomplete, and in containerized production it is often wrong. This article explains what the woocommerce defer transactional emails action scheduler hpos combination really does, how to diagnose silent email loss with SQL and WP-CLI, and how to ship a must-use plugin that routes every transactional email through Action Scheduler with deterministic retries.

The Myth: woocommerce_defer_transactional_emails Does Not Use WP-Cron

Most tutorials, and most AI assistants, tell you to add this and call it done:

add_filter( 'woocommerce_defer_transactional_emails', '__return_true' );

They then claim WooCommerce schedules the emails with WP-Cron after a short delay (usually quoted as 10 seconds). That is not what happens, and the difference matters the first time an order email goes missing.

What core actually does

In includes/class-wc-emails.php, enabling the filter makes WC_Emails register queue_transactional_email() on every hook in woocommerce_email_actions instead of sending inline. The queued payloads are then routed through Automattic\WooCommerce\Internal\Email\DeferredEmailQueue and the legacy WC_Background_Emailer, which is built on the WP_Background_Process (wp-background-processing) library. Which of the two handles your site depends on the WooCommerce version you run, so check the class on your own release. The mechanism is the same in spirit:

  1. The checkout request pushes [ $filter, $args ] tuples into an in-memory queue.
  2. On PHP shutdown, the legacy background emailer persists the queue and initiates a non-blocking wp_remote_post() HTTP request to the site's own admin-ajax.php. This fire-and-forget WordPress HTTP API call allows the original checkout request to finish without waiting for the separate background email processing request to complete.
  3. That loopback request spawns a second PHP process, which drains the queue by calling WC_Emails::send_queued_transactional_email( $filter, $args ).

There is no cron event, no scheduled timestamp, and no delay. There is an HTTP request from your server to itself, sent without waiting for the response. If that request does not arrive, nothing retries it.

Why the loopback silently drops emails

Because the dispatch is fire-and-forget, a failure produces no error in the checkout request and no admin notice. Typical causes:

  • Kubernetes and container networks. A pod resolves its public hostname to a load balancer or ingress it cannot reach from inside the cluster (hairpin NAT, missing egress rule, or a service mesh policy). The loopback never leaves the pod.
  • Cloudflare WAF and bot rules. The loopback arrives from a server IP with no browser fingerprint, and a managed rule, rate limit, or challenge page rejects admin-ajax.php POSTs.
  • TLS and protocol mismatches. TLS termination at the edge with a different certificate chain or protocol on the origin yields cURL error 35 (SSL connect error). HTTP basic auth on staging-style environments produces a 401 for the same reason.

When the loopback fails, the serialized batch stays in wp_options until some later request manages to trigger the queue. Customers experience this as intermittent, unexplained missing emails. In WooCommerce versions before 10.8, a WC_Background_Emailer loopback failure can leave queued transactional notifications unprocessed when the asynchronous admin-ajax.php request is blocked by a firewall, DNS routing issue, TLS error, or exhausted PHP worker pool. This makes HTTP loopback reliability an important diagnostic factor for legacy WooCommerce email delivery.

Why naive Action Scheduler wrappers fail under HPOS

The obvious fix is to unhook the notification actions (for example woocommerce_order_status_completed) and call WC_Emails::send_queued_transactional_email( $filter, $args ) from an Action Scheduler job. Two production failures follow:

  • Serialized WC_Order objects. Many hooks pass the order object as a second argument. If you put that object in the job arguments, the worker later runs with a stale or partially initialized instance. Third-party PDF invoice and fulfillment plugins that hook woocommerce_email_attachments, order_details, order_meta, and fulfillment_details expect fresh metadata hydrated by OrdersTableDataStore. They render invoices with missing line items, wrong totals, or no attachment at all. Store the scalar order ID and let the worker re-hydrate. HPOS order object serialization and CRUD data access introduce a data consistency risk when background jobs store complete WC_Order instances instead of stable order identifiers. A serialized order object may contain outdated metadata by the time the email worker executes, so the safer approach is to store the scalar order ID and retrieve a fresh order through wc_get_order() when the notification callback requires an order object.
  • Notification hooks that never reach the mail layer. Even when woocommerce_checkout_order_processed completes and the order moves to processing in HPOS, a misfired notification hook can prevent WC_Email_New_Order and the customer confirmation from reaching wp_mail(). This is the failure pattern discussed in WooCommerce issue #68552.

The long-running discussion of these trade-offs, including deferral behavior and checkout latency, is tracked in WooCommerce GitHub issues #6603, #14151, #22806, and #68552.

Flowchart comparing synchronous SMTP and fragile WC_Background_Emailer HTTP loopbacks against deterministic Action Scheduler email jobs with HPOS cache hydration.

Diagnostic Workflow

Before changing anything, establish whether you are losing emails to a broken loopback, a broken mail transport, or both. Replace the wp_ prefix with your own table prefix.

1. Look for stuck background-process batches

A failed loopback leaves its batch behind as a row in wp_options, contributing to the same wp_options table bloat and unindexed query overhead that slows down uncached checkout requests. The option name is built from the background process identifier, so the query matches both common spellings:

-- 1. Stuck wp-background-processing email batches (failed HTTP loopbacks)
SELECT
    option_id,
    option_name,
    LENGTH(option_value)     AS payload_bytes,
    LEFT(option_value, 250)  AS payload_preview
FROM wp_options
WHERE option_name LIKE '%wc_background_emailer_batch%'
   OR option_name LIKE '%wc_emailer_batch%'
ORDER BY option_id DESC;

Any row older than a minute or two is suspect. A healthy site shows zero or one very recent row. Several old rows with payloads that mention woocommerce_order_status_* hooks mean the loopback is failing.

2. Audit recent paid HPOS orders

This query lists paid orders from the last 24 hours together with the new_order_email_sent flag from the HPOS operational data table and a count of order notes that mention email. WooCommerce does not write a dispatch note for every email by default, so treat the note count as a signal when you or a plugin log mail activity as order notes, not as ground truth.

-- 2. Recent paid HPOS orders with no sign of email dispatch
SELECT
    o.id                  AS order_id,
    o.status,
    o.billing_email,
    o.date_created_gmt,
    op.date_paid_gmt,
    op.new_order_email_sent,
    COUNT(c.comment_ID)   AS email_notes
FROM wp_wc_orders o
INNER JOIN wp_wc_order_operational_data op
        ON op.order_id = o.id
LEFT JOIN wp_comments c
       ON c.comment_post_ID = o.id
      AND c.comment_type = 'order_note'
      AND ( c.comment_content LIKE '%email%' OR c.comment_content LIKE '%e-mail%' )
WHERE o.type = 'shop_order'
  AND o.status IN ( 'wc-processing', 'wc-completed' )
  AND o.date_created_gmt > ( UTC_TIMESTAMP() - INTERVAL 24 HOUR )
GROUP BY
    o.id, o.status, o.billing_email, o.date_created_gmt,
    op.date_paid_gmt, op.new_order_email_sent
HAVING email_notes = 0
    OR op.new_order_email_sent IS NULL
    OR op.new_order_email_sent = 0
ORDER BY o.id DESC
LIMIT 25;

Cross-check hits against your SMTP provider's activity log. If the provider never saw the message, the email died before wp_mail(), which points at the queue rather than the relay.

3. Test the loopback from the server itself

Run this from the same container or host that serves checkout, as the same user that runs PHP. It mirrors the arguments WordPress's background process uses, including the local SSL verification filter:

# 3. Does an internal wp_remote_post() loopback succeed, or is it blocked by SSL/WAF/DNS?
wp eval '
$res = wp_remote_post(
    admin_url( "admin-ajax.php" ),
    [
        "timeout"   => 5,
        "blocking"  => true,
        "sslverify" => apply_filters( "https_local_ssl_verify", false ),
    ]
);
echo is_wp_error( $res )
    ? "ERROR: " . $res->get_error_message()
    : "HTTP " . wp_remote_retrieve_response_code( $res );
echo PHP_EOL;
' --allow-root

A clean HTTP 400 or HTTP 200 from admin-ajax.php means the loopback path works. cURL error 35, a timeout, a DNS failure, or a 403 or 401 means deferred emails on this host are being dropped. Drop --allow-root if you do not run WP-CLI as root.

Production-Ready Solution: An Action Scheduler Offloader as a Must-Use Plugin

The design replaces the loopback with a database-backed job. Action Scheduler writes each job to wp_actionscheduler_actions, tracks its status, and exposes failures, which is the observability the background emailer never had. Save the file as wp-content/mu-plugins/enterprise-async-emails.php.

<?php
/**
 * Plugin Name: Enterprise Action Scheduler Transactional Email Offloader
 * Description: Replaces fragile HTTP loopback email deferral with deterministic Action Scheduler jobs and HPOS hydration.
 * Version: 1.1.0
 */

declare(strict_types=1);

namespace EnterpriseWC\AsyncEmails;

use WC_Emails;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Raised when wp_mail() reports a transport failure inside the worker.
 */
final class SmtpTransportException extends \RuntimeException {}

final class ActionSchedulerEmailQueue {

    private const ASYNC_HOOK   = 'enterprise_wc_send_queued_transactional_email';
    private const ASYNC_GROUP  = 'wc-transactional-emails';
    private const MAX_ATTEMPTS = 4;

    /**
     * True while the worker is calling WC_Emails. Prevents the interceptor from
     * swallowing the very call the worker makes.
     */
    private static bool $is_worker_running = false;

    public static function init(): void {
        // Make WooCommerce register queue_transactional_email() on every notification hook.
        add_filter( 'woocommerce_defer_transactional_emails', '__return_true', 999 );

        // Divert queued emails into Action Scheduler instead of WC_Background_Emailer.
        add_filter( 'woocommerce_allow_send_queued_transactional_email', [ self::class, 'intercept_and_schedule_email' ], 10, 3 );

        // Worker callback. The third argument is only present on retries.
        add_action( self::ASYNC_HOOK, [ self::class, 'process_scheduled_email' ], 10, 3 );

        // Bounded retry for transient SMTP failures.
        add_action( 'action_scheduler_failed_execution', [ self::class, 'schedule_retry' ], 10, 2 );
    }

    /**
     * Intercept the queued email and enqueue it in Action Scheduler.
     *
     * @param bool   $allow  Whether WooCommerce should send the email now.
     * @param string $filter The notification hook (e.g. woocommerce_order_status_pending_to_processing).
     * @param array  $args   Hook arguments (order ID, order object, and so on).
     * @return bool False to stop WooCommerce from sending; the original value when Action Scheduler is unavailable.
     */
    public static function intercept_and_schedule_email( bool $allow, string $filter, array $args ): bool {
        // The worker is the one calling send_queued_transactional_email(); let it through.
        if ( self::$is_worker_running ) {
            return $allow;
        }

        if ( ! function_exists( 'as_enqueue_async_action' ) || ! function_exists( 'as_has_scheduled_action' ) ) {
            return $allow;
        }

        $filter = sanitize_key( $filter );
        if ( '' === $filter ) {
            return $allow;
        }

        // Never serialize WC_Order instances: reduce any object with get_id() to its integer ID.
        $normalized_args = array_map(
            static function ( $arg ) {
                if ( is_object( $arg ) && method_exists( $arg, 'get_id' ) ) {
                    return (int) $arg->get_id();
                }
                return $arg;
            },
            $args
        );

        $payload = [
            'filter' => $filter,
            'args'   => $normalized_args,
        ];

        // Skip if an identical job is already pending or running.
        if ( ! as_has_scheduled_action( self::ASYNC_HOOK, $payload, self::ASYNC_GROUP ) ) {
            as_enqueue_async_action( self::ASYNC_HOOK, $payload, self::ASYNC_GROUP );
        }

        // Short-circuit WC_Emails::send_queued_transactional_email().
        return false;
    }

    /**
     * Send the email inside the Action Scheduler worker.
     *
     * @param string $filter  Original WooCommerce notification hook.
     * @param array  $args    Scalar arguments for that hook.
     * @param int    $attempt Attempt number (1 on the first run).
     * @throws SmtpTransportException When wp_mail() reports a failure.
     */
    public static function process_scheduled_email( string $filter, array $args, int $attempt = 1 ): void {
        if ( '' === $filter || empty( $args ) ) {
            return;
        }

        // Drop cached order state so OrdersTableDataStore hydrates fresh HPOS metadata.
        $primary_id = isset( $args[0] ) && is_numeric( $args[0] ) ? (int) $args[0] : 0;
        if ( $primary_id > 0 ) {
            wp_cache_delete( 'order-' . $primary_id, 'orders' );
            clean_post_cache( $primary_id );
        }

        // Capture wp_mail() failures so the job can fail and be retried.
        $mail_error     = null;
        $error_listener = static function ( \WP_Error $error ) use ( &$mail_error ): void {
            $mail_error = $error;
        };
        add_action( 'wp_mail_failed', $error_listener );

        self::$is_worker_running = true;

        try {
            // Load the mailer and every third-party attachment/template filter.
            WC()->mailer();
            WC_Emails::send_queued_transactional_email( $filter, $args );
        } finally {
            self::$is_worker_running = false;
            remove_action( 'wp_mail_failed', $error_listener );
        }

        if ( $mail_error instanceof \WP_Error ) {
            throw new SmtpTransportException(
                sprintf(
                    'SMTP transport failure on hook [%s] for Order #%d (attempt %d): %s',
                    $filter,
                    $primary_id,
                    $attempt,
                    $mail_error->get_error_message()
                )
            );
        }
    }

    /**
     * Re-schedule a failed email job with exponential backoff (1, 2, 4 minutes).
     *
     * @param mixed      $action_id Failed action ID.
     * @param \Throwable $exception The exception thrown by the worker.
     */
    public static function schedule_retry( $action_id, $exception ): void {
        if ( ! $exception instanceof SmtpTransportException ) {
            return;
        }

        if ( ! class_exists( 'ActionScheduler' ) || ! function_exists( 'as_schedule_single_action' ) ) {
            return;
        }

        $action = \ActionScheduler::store()->fetch_action( (string) $action_id );
        if ( self::ASYNC_HOOK !== $action->get_hook() ) {
            return;
        }

        $params  = $action->get_args();
        $attempt = isset( $params['attempt'] ) ? (int) $params['attempt'] : 1;

        if ( $attempt >= self::MAX_ATTEMPTS ) {
            wc_get_logger()->error(
                'Giving up on transactional email after ' . $attempt . ' attempts: ' . $exception->getMessage(),
                [ 'source' => 'transactional-emails' ]
            );
            return;
        }

        $params['attempt'] = $attempt + 1;

        as_schedule_single_action(
            time() + ( MINUTE_IN_SECONDS * ( 2 ** ( $attempt - 1 ) ) ),
            self::ASYNC_HOOK,
            $params,
            self::ASYNC_GROUP
        );
    }
}

ActionSchedulerEmailQueue::init();

How the pieces fit

Priority 999 on the defer filter. woocommerce_defer_transactional_emails is evaluated when WooCommerce wires its notification hooks. Running late at 999 overrides any plugin that returns false at the default priority, so every trigger is registered through queue_transactional_email().

Interception in intercept_and_schedule_email(). The filter woocommerce_allow_send_queued_transactional_email receives $allow, $filter, and $args. The method confirms Action Scheduler is loaded, converts anything with get_id() into an integer, skips the enqueue if an identical job is pending or in progress, enqueues the job in the wc-transactional-emails group, and returns false. Using the same normalized payload for the check and the enqueue matters: Action Scheduler compares arguments exactly, so a mismatch (for example, sanitizing the hook name on only one side) quietly disables deduplication. The check covers in-flight jobs only; if a payment webhook and browser redirect complete the same order a few seconds apart, pair this queue with a per-order MySQL mutex to prevent Stripe and PayPal webhook race conditions from firing the transition hook twice.

Fresh state in process_scheduled_email(). The worker takes the first scalar as the primary order ID, evicts the order from the local object cache with wp_cache_delete( 'order-' . $primary_id, 'orders' ), and calls clean_post_cache(), so OrdersTableDataStore reads current HPOS rows when PDF plugins ask for attachments, order_details, order_meta, or fulfillment_details.

Failure capture. wp_mail() catches PHPMailer exceptions and fires wp_mail_failed instead of throwing. The temporary listener records the WP_Error, and after WC_Emails::send_queued_transactional_email() returns, the worker throws. The finally block removes the listener on every path, including fatal-adjacent exceptions from a template, so one failed job cannot leak a listener into the next job in the same worker process.

Two corrections to the naive version

Both changes below are in the code above, and both address bugs that appear in the common version of this pattern.

  1. Re-entrancy guard. WC_Emails::send_queued_transactional_email() itself applies woocommerce_allow_send_queued_transactional_email. Without the $is_worker_running flag, the worker would call the method, hit your own interceptor, receive false, and re-enqueue the same job forever without sending anything.
  2. Retries are not automatic. Throwing an exception marks the Action Scheduler job as failed. Core Action Scheduler does not reschedule failed jobs on its own. The action_scheduler_failed_execution handler adds a bounded retry with exponential backoff, and it only fires for SmtpTransportException, so template bugs and fatals do not loop. If a hook sends several emails (admin and customer), a retry re-sends all of them, so keep the attempt cap low. SMTP relay timeout retry backoff should distinguish temporary mail transport failures from permanent configuration or authentication errors. For transient failures, bounded exponential backoff intervals, such as 1, 2, and 4 minutes, help prevent repeated connection attempts from overwhelming an already struggling SMTP relay. Retry attempts should also be logged and designed to minimize duplicate email delivery if the original message was accepted before the connection timed out.

Run the Queue Without Another Loopback

Action Scheduler's default async runner also starts with a loopback to admin-ajax.php, and falls back to WP-Cron. On hosts where the loopback fails, jobs would wait for WP-Cron, which only runs when someone visits the site. Run the queue from the system scheduler instead, and disable the async request runner (see our full guide on offloading Action Scheduler queues to isolated WP-CLI workers and eliminating Error 1213 deadlocks):

// In an mu-plugin: let cron or CLI own queue execution.
add_filter( 'action_scheduler_allow_async_request_runner', '__return_false' );
# /etc/cron.d/wc-action-scheduler  (every minute)
* * * * * www-data wp action-scheduler run --group=wc-transactional-emails --batch-size=25 --batches=1 --path=/var/www/html --quiet

On Kubernetes, run the same command from a CronJob that uses your application image, or from a sidecar loop, so the worker never depends on pod-to-ingress routing. Allow this schedule to finish within its interval; a one-minute cadence with a 25-job batch size is a reasonable starting point for most stores.

Verify the Result

Place a test order and confirm three things. First, POST /?wc-ajax=checkout should return in normal gateway time, with no SMTP or PDF cost in the trace. Second, the queue should hold scalar IDs, never serialized objects:

-- Inspect the email jobs and their payloads
SELECT
    a.action_id,
    a.status,
    a.scheduled_date_gmt,
    a.last_attempt_gmt,
    LEFT(a.args, 120) AS args
FROM wp_actionscheduler_actions a
INNER JOIN wp_actionscheduler_groups g
        ON g.group_id = a.group_id
WHERE g.slug = 'wc-transactional-emails'
  AND a.status IN ( 'pending', 'in-progress', 'failed' )
ORDER BY a.action_id DESC
LIMIT 25;

Payloads should look like {"filter":"woocommerce_order_status_pending_to_processing","args":[1234,1234]}. Third, rerun diagnostic queries 1 and 2 from earlier. Query 1 should return no growing set of old rows, and the audit in Query 2 should be empty once the queue has drained. For failure testing, point the SMTP host at an unroutable address and confirm the job moves to failed, a retry is scheduled, and an eventual success clears it.

Limits and Operational Notes

  • Where interception happens. The woocommerce_allow_send_queued_transactional_email filter runs inside send_queued_transactional_email(), which is the method the deferred queue calls when it drains. Confirm on your WooCommerce version when and in which process that drain occurs. If your version still dispatches the legacy loopback to drain the queue, the interceptor runs only once that dispatch lands, and the strictest fix is to unhook queue_transactional_email from the actions in woocommerce_email_actions and enqueue Action Scheduler jobs directly at trigger time.
  • Order of delivery. Jobs are not guaranteed to run in the order they were enqueued. Do not depend on the customer email arriving after the admin email.
  • Plugin compatibility. PDF plugins that cache a generated file per order should invalidate it on the same status transition that triggers the email. The cache flush in the worker covers WooCommerce's own order cache, not a plugin's file cache.
  • Observability. Failed jobs appear under Tools > Scheduled Actions > Failed, filtered by the wc-transactional-emails group. Alert on that count.

Summary

Synchronous SMTP and PDF rendering put mail latency directly into the checkout response, and the stock deferral filter swaps that for a fire-and-forget HTTP loopback that fails silently in Kubernetes, behind Cloudflare, and under TLS mismatches. The woocommerce defer transactional emails action scheduler hpos pattern replaces the loopback with persistent, inspectable jobs: scalar order IDs in the payload, a cache flush before hydration, a failure signal from wp_mail_failed, bounded retries, and a worker driven by cron rather than by another HTTP request to yourself. Diagnose first with the three snippets above, deploy the mu-plugin, and measure checkout latency and the failed-job count before and after.

0 Comments