ghost 6.62.0 → 6.64.0

package/core/server/services/email-analytics/email-analytics-service-wrapper.js

@@ -75,7 +75,7 @@ class EmailAnalyticsServiceWrapper {
         }
         return result;
     }
-    _logJobCompletion(jobType, fetchResult, totalDurationMs) {
+    _logJobCompletion(jobType, fetchResult, totalDurationMs, lagSeconds = null) {
         const config = this.#getConfig();
         const { eventCount, apiPollingTimeMs, processingTimeMs, aggregationTimeMs, emailAggregationTimeMs, memberAggregationTimeMs, result, } = fetchResult;
         if (eventCount === 0) {
@@ -89,6 +89,7 @@ class EmailAnalyticsServiceWrapper {
         const logMessage = [
             `[Background Job] ${this.#backgroundJobName} processed ${jobType} | ${this.#logPrefix}`,
             `${eventCount} events in ${(totalDurationMs / 1000).toFixed(1)}s (${throughput.toFixed(2)} events/s)`,
+            ...(lagSeconds === null ? [] : [`Lag: ${(lagSeconds / 60).toFixed(1)}m`]),
             `Mode: ${batchMode}`,
             `Timings: API ${(apiPollingTimeMs / 1000).toFixed(1)}s (${apiPercent}%) / Processing ${(processingTimeMs / 1000).toFixed(1)}s (${processingPercent}%) / Aggregation ${(aggregationTimeMs / 1000).toFixed(1)}s (${aggregationPercent}%) [Email ${(emailAggregationTimeMs / 1000).toFixed(1)}s / Member ${(memberAggregationTimeMs / 1000).toFixed(1)}s]`,
             `Events: opened=${result.opened} delivered=${result.delivered} failed=${result.permanentFailed + result.temporaryFailed} unprocessable=${result.unprocessable}`,
@@ -100,6 +101,7 @@ class EmailAnalyticsServiceWrapper {
                 task: jobType,
                 event_count: eventCount,
                 duration_ms: totalDurationMs,
+                ...(lagSeconds === null ? {} : { lag_seconds: lagSeconds }),
             },
         }, logMessage);
         // We're only concerned with open throughput as this is displayed to users and is most sensitive to being up to date
@@ -124,46 +126,30 @@ class EmailAnalyticsServiceWrapper {
             }
         }
     }
-    async fetchLatestOpenedEvents({ maxEvents = Infinity, } = {}) {
-        const config = this.#getConfig();
-        const beginTimestamp = await this.service.getLastOpenedEventTimestamp();
-        const lagMinutes = (Date.now() - beginTimestamp.getTime()) / 60000;
-        const lagThreshold = config.get('emailAnalytics:openedJobLagWarningMinutes');
-        // NOTE: We only update the begin timestamp when we process events, so there's cases where we can have a false positive
-        //  - Ghost or Mailgun outages
-        //  - Lack of actual email activity
-        if (lagThreshold && lagMinutes > lagThreshold) {
-            logging_1.default.warn(`${this.#logPrefix} Opened events processing is ${lagMinutes.toFixed(1)} minutes behind (threshold: ${lagThreshold})`);
-        }
+    async #fetchAndLog(jobType, fetch, lagPipeline) {
         const fetchStartedAt = Date.now();
-        const fetchResult = await this.service.fetchLatestOpenedEvents({ maxEvents });
+        const fetchResult = await fetch();
         const totalDuration = Date.now() - fetchStartedAt;
-        this._logJobCompletion('latest-opened', fetchResult, totalDuration);
+        // Lag is read after the fetch so a clean run counts as caught up
+        const lagSeconds = lagPipeline ? this.service.getStatus()[lagPipeline].lagSeconds : null;
+        this._logJobCompletion(jobType, fetchResult, totalDuration, lagSeconds);
         return fetchResult.eventCount;
     }
+    async fetchLatestOpenedEvents({ maxEvents = Infinity, } = {}) {
+        return this.#fetchAndLog('latest-opened', () => this.service.fetchLatestOpenedEvents({ maxEvents }), 'latestOpened');
+    }
     async fetchLatestNonOpenedEvents({ maxEvents = Infinity, } = {}) {
-        const fetchStartedAt = Date.now();
-        const fetchResult = await this.service.fetchLatestNonOpenedEvents({ maxEvents });
-        const totalDuration = Date.now() - fetchStartedAt;
-        this._logJobCompletion('latest', fetchResult, totalDuration);
-        return fetchResult.eventCount;
+        return this.#fetchAndLog('latest', () => this.service.fetchLatestNonOpenedEvents({ maxEvents }), 'latest');
     }
     async fetchMissing({ maxEvents = Infinity } = {}) {
-        const fetchStartedAt = Date.now();
-        const fetchResult = await this.service.fetchMissing({ maxEvents });
-        const totalDuration = Date.now() - fetchStartedAt;
-        this._logJobCompletion('missing', fetchResult, totalDuration);
-        return fetchResult.eventCount;
+        // The missing-events sweep trails the delivery pipeline by design, so it has no lag of its own
+        return this.#fetchAndLog('missing', () => this.service.fetchMissing({ maxEvents }));
     }
     async fetchScheduled({ maxEvents }) {
         if (maxEvents < 300) {
             return 0;
         }
-        const fetchStartedAt = Date.now();
-        const fetchResult = await this.service.fetchScheduled({ maxEvents });
-        const totalDuration = Date.now() - fetchStartedAt;
-        this._logJobCompletion('scheduled', fetchResult, totalDuration);
-        return fetchResult.eventCount;
+        return this.#fetchAndLog('scheduled', () => this.service.fetchScheduled({ maxEvents }));
     }
     async startFetch() {
         const startedAt = Date.now();

package/core/server/services/email-analytics/email-analytics-service.js

@@ -65,11 +65,18 @@ class EmailAnalyticsService {
         this.queries.setJobMetadata(this.#jobNames.scheduled, null);
     }
     getStatus() {
+        const now = Date.now();
+        const withLag = (data) => Object.assign(data, {
+            fetchedThrough: data.fetchedThrough ?? null,
+            lagSeconds: data.fetchedThrough
+                ? Math.max(0, Math.floor((now - data.fetchedThrough.getTime()) / 1000))
+                : null,
+        });
         return {
-            latest: this.#fetchLatestNonOpenedData,
-            missing: this.#fetchMissingData,
+            latest: withLag(this.#fetchLatestNonOpenedData),
+            missing: withLag(this.#fetchMissingData),
             scheduled: this.#fetchScheduledData,
-            latestOpened: this.#fetchLatestOpenedData,
+            latestOpened: withLag(this.#fetchLatestOpenedData),
         };
     }
     /**
@@ -363,6 +370,7 @@ class EmailAnalyticsService {
                 });
             }
         };
+        let fetchedThrough;
         try {
             const fetchResult = await this.#fetchEvents({
                 batchHandler: processBatch,
@@ -371,6 +379,11 @@ class EmailAnalyticsService {
                 maxEvents,
                 events: eventTypes,
             });
+            // A void result means fetching was skipped (for example, Mailgun is not configured).
+            // Empty successful windows still establish progress through their requested end.
+            if (fetchResult) {
+                fetchedThrough = fetchResult.safeCursor ?? end;
+            }
             if (fetchResult?.safeCursor &&
                 (!fetchData.lastEventTimestamp || fetchResult.safeCursor < fetchData.lastEventTimestamp)) {
                 fetchData.lastEventTimestamp = fetchResult.safeCursor;
@@ -425,6 +438,9 @@ class EmailAnalyticsService {
         if (error) {
             throw error;
         }
+        if (fetchedThrough) {
+            fetchData.fetchedThrough = fetchedThrough;
+        }
         return {
             eventCount,
             apiPollingTimeMs,

package/core/server/services/email-analytics/index.js

@@ -50,8 +50,13 @@ const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList,
         prometheusClient,
     });
     const newsletterMailgunTags = ['bulk-email'];
-    if (config.get('bulkEmail:mailgun:tag')) {
-        newsletterMailgunTags.push(config.get('bulkEmail:mailgun:tag'));
+    const automationMailgunTags = [constants_1.AUTOMATION_EMAIL_TAG];
+    const giftMailgunTags = [constants_2.GIFT_DELIVERY_EMAIL_TAG];
+    const mailgunTagFromConfig = config.get('bulkEmail:mailgun:tag');
+    if (mailgunTagFromConfig) {
+        newsletterMailgunTags.push(mailgunTagFromConfig);
+        automationMailgunTags.push(mailgunTagFromConfig);
+        giftMailgunTags.push(mailgunTagFromConfig);
     }
     prometheusClient?.registerCounter({
         name: newsletter_email_analytics_batch_processor_1.AGGREGATE_MEMBER_STATS_METRIC_NAME,
@@ -91,7 +96,7 @@ const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList,
         domainEvents,
         event: start_automation_email_analytics_job_event_1.StartAutomationEmailAnalyticsJobEvent,
         queries,
-        mailgunTags: [constants_1.AUTOMATION_EMAIL_TAG],
+        mailgunTags: automationMailgunTags,
         jobNames: {
             latestNonOpened: 'email-analytics-automation-latest-others',
             missing: 'email-analytics-automation-missing',
@@ -116,7 +121,7 @@ const init = ({ automationsApi, config, db, domainEvents, emailSuppressionList,
         domainEvents,
         event: start_gift_email_analytics_job_event_1.StartGiftEmailAnalyticsJobEvent,
         queries,
-        mailgunTags: [constants_2.GIFT_DELIVERY_EMAIL_TAG],
+        mailgunTags: giftMailgunTags,
         jobNames: {
             latestNonOpened: 'email-analytics-gifts-latest-others',
             missing: 'email-analytics-gifts-missing',

package/core/server/services/email-rendering/finalize.js

@@ -1,4 +1,4 @@
-const cheerio = require('cheerio');
+const cheerio = require('cheerio/slim');
 const juice = require('juice');
 const htmlToPlaintext = require('@tryghost/html-to-plaintext');
 
@@ -12,7 +12,12 @@ const finalizeHtml = (html) => {
   $('figcaption').addClass('kg-card-figcaption');
   html = $.html();
 
-  const juicedHtml = juice(html, { inlinePseudoElements: true, removeStyleTags: true });
+  // resolveCSSVariables crashes on nameless declarations in user-authored style attributes
+  const juicedHtml = juice(html, {
+    inlinePseudoElements: true,
+    removeStyleTags: true,
+    resolveCSSVariables: false,
+  });
 
   // Many email clients, like Outlook and Yahoo, [lack support for <figure>
   // and <figcaption>][0]. To work around this, change the tags to <div>s.

package/core/server/services/email-service/CONTEXT.md

@@ -0,0 +1,37 @@
+# Newsletter Email Sending
+
+Newsletter Email Sending covers the preparation and submission of newsletter emails to the configured email provider.
+
+## Language
+
+**Sending status**:
+The state of a newsletter email's send: preparing, submitting, submitted, or failed. It is separate from any later provider-reported outcome.
+_Avoid_: Delivery status, provider outcome
+
+**Sending phase**:
+The part of a send, before it is submitted or fails, that progress and failures are reported against: preparing or submitting.
+_Avoid_: Step, stage
+
+**Preparing**:
+The sending phase while none of a newsletter email's recipient batches has started submitting, including before any sending work has begun.
+_Avoid_: Pending, queued
+
+**Submitting**:
+The sending phase once at least one recipient batch has started submitting to the configured email provider and the send has not yet been submitted or failed.
+_Avoid_: Sending, delivering
+
+**Sending progress**:
+The completed and total recipient counts for the current sending phase.
+_Avoid_: Delivery progress, expected count
+
+**Submitted**:
+Every batch of a newsletter email has been accepted by the configured email provider. Submission does not mean that recipients have received the email.
+_Avoid_: Sent, delivered
+
+**Failed**:
+Sending stopped with an error and will not continue without a retry.
+_Avoid_: Bounced, rejected
+
+**Failed during**:
+The sending phase a failed newsletter email was in when sending stopped.
+_Avoid_: Failure step

package/core/server/services/email-service/README.md

@@ -0,0 +1,45 @@
+# Email service
+
+Renders newsletter emails, splits them into recipient batches, and submits the
+batches to the configured email provider. Domain terms live in
+[CONTEXT.md](CONTEXT.md).
+
+## Sending status
+
+The sending status served by the Admin API's `emails/:id/status` endpoint is
+derived on read. `sending-status.ts` owns the derivation from an email and its
+batches with their recipient counts; `SendingStatusService` reads those rows
+and `sending-status-serializers.ts` shapes the response. Submitted is terminal and the batch aggregation only
+describes a send that is still in progress or has failed, so submitted emails answer with the email's stored
+`email_count` as both completed and total; batch creation reconciles that
+column to the recipient rows it built. That also keeps reads of long-finished
+emails cheap, with no query over the batches or recipients. The endpoint is always available; Admin decides
+whether to poll it while a send is active.
+
+The phase is read from the batches: an email is submitting once any batch has
+left `pending`, and preparing otherwise. Batch statuses persist across
+attempts, so a retried email reports submitting with frozen progress while it
+waits for its job, and `failed_during` is the same derivation applied to a
+failed email.
+
+The rough ETA measures recent recipient throughput, including work completed by
+concurrent workers. It stays `null` until enough timing samples are available in
+the current phase and attempt, so short sends may finish without showing an ETA.
+The rate uses the last minute of completions, including the interval crossing
+the window boundary. Early estimates use the available history. Sparse sends
+retain at least two measured intervals.
+Progress counts update independently of the estimate.
+
+The ETA is always `null` for failed emails and `0` once no work remains in the
+current phase. Batches that failed during the current attempt are not remaining
+work until the email is retried, so the ETA can reach `0` while completed is
+still below total. Consumers should key completion on the status, never the ETA.
+
+Ghost does not record when a sending attempt or phase started, so the ETA uses
+the email's `updated_at` as a proxy for the start of the current attempt: the
+sending job saves the email when it takes its status lock and, when the
+recipient count changed, again after creating batches; a retry or boot resume
+saves it when re-queuing the email. Batches completed before that timestamp
+belong to an earlier attempt and are left out of the rate window. The proxy
+only holds while nothing saves the Email model, or sets `emails.updated_at`
+through a raw update, while batches are being submitted.

package/core/server/services/email-service/batch-sending-service.js

@@ -213,6 +213,7 @@ class BatchSendingService {
 
     // Check if email is 'pending' only + change status to submitting in one transaction.
     // This allows us to have a lock around the email job that makes sure an email can only have one active job.
+    // Also stamps updated_at, which SendingStatusService reads as the attempt start; do not save the Email once batches submit.
     let email;
     try {
       email = await this.retryDb(
@@ -704,6 +705,7 @@ class BatchSendingService {
     const deliveryTimes = this.calculateDeliveryTimes(email, batches.length);
 
     // Loop batches and send them via the EmailProvider
+    // SendingStatusService treats a batch that fails in this run as finished work; never re-queue it within the run.
     let succeededCount = 0;
     const queue = batches.slice();
 

package/core/server/services/email-service/email-controller.js

@@ -1,6 +1,8 @@
 const errors = require('@tryghost/errors');
 const tpl = require('@tryghost/tpl');
 
+/** @typedef {import('./sending-status-service').SendingStatusService} SendingStatusService */
+
 const messages = {
   postNotFound: 'Post not found.',
   noEmailsProvided: 'No emails provided.',
@@ -23,16 +25,18 @@ class EmailController {
   service;
   models;
   getRequiredUrlRelations;
+  sendingStatusService;
 
   /**
    *
    * @param {EmailService} service
-   * @param {{models: {Post: any, Newsletter: any, Email: any}, getRequiredUrlRelations?: () => string[]}} dependencies
+   * @param {{models: {Post: any, Newsletter: any, Email: any}, getRequiredUrlRelations?: () => string[], sendingStatusService: SendingStatusService}} dependencies
    */
-  constructor(service, { models, getRequiredUrlRelations = () => [] }) {
+  constructor(service, { models, getRequiredUrlRelations = () => [], sendingStatusService }) {
     this.service = service;
     this.models = models;
     this.getRequiredUrlRelations = getRequiredUrlRelations;
+    this.sendingStatusService = sendingStatusService;
   }
 
   async _getFrameData(frame) {
@@ -143,6 +147,18 @@ class EmailController {
 
     return await this.service.retryEmail(email);
   }
+
+  async getSendingStatus(frame) {
+    const status = await this.sendingStatusService.statusFor(frame.data.id);
+
+    if (!status) {
+      throw new errors.NotFoundError({
+        message: tpl(messages.emailNotFound),
+      });
+    }
+
+    return status;
+  }
 }
 
 module.exports = EmailController;

package/core/server/services/email-service/email-renderer.js

@@ -192,7 +192,7 @@ function escapeRegExp(string) {
  * @return {ReturnType<typeof cheerio.load>}
  */
 function cheerioLoad(html) {
-  const cheerio = require('cheerio');
+  const cheerio = require('cheerio/slim');
   return cheerio.load(html);
 }
 
@@ -709,7 +709,12 @@ class EmailRenderer {
 
     // Juice HTML (inline CSS)
     const juice = require('juice');
-    html = juice(html, { inlinePseudoElements: true, removeStyleTags: true });
+    // resolveCSSVariables crashes on nameless declarations in user-authored style attributes
+    html = juice(html, {
+      inlinePseudoElements: true,
+      removeStyleTags: true,
+      resolveCSSVariables: false,
+    });
 
     // happens after inlining of CSS so we can change element types without worrying about styling
     $ = cheerioLoad(html);

package/core/server/services/email-service/email-service-wrapper.js

@@ -24,6 +24,7 @@ class EmailServiceWrapper {
     const EmailRenderer = require('./email-renderer');
     const SendingService = require('./sending-service');
     const BatchSendingService = require('./batch-sending-service');
+    const { SendingStatusService } = require('./sending-status-service');
     const EmailSegmenter = require('./email-segmenter');
     const MailgunEmailProvider = require('./mailgun-email-provider');
     const { DomainWarmingService } = require('./domain-warming-service');
@@ -43,7 +44,7 @@ class EmailServiceWrapper {
     const limitService = require('../limits');
     const labs = require('../../../shared/labs');
     const emailAddressService = require('../email-address');
-    const i18nLib = require('@tryghost/i18n');
+    const i18nLib = require('@tryghost/i18n').default;
     const lexicalLib = require('../../lib/lexical');
     const urlUtils = require('../../../shared/url-utils').default;
     const memberAttribution = require('../member-attribution');
@@ -127,6 +128,7 @@ class EmailServiceWrapper {
       sentry,
       getRequiredUrlRelations,
     });
+    const sendingStatusService = new SendingStatusService({ knex: db.knex });
 
     if (ghostServer) {
       // Two phases: stop claiming batches immediately, drain in-flight ones later.
@@ -169,6 +171,7 @@ class EmailServiceWrapper {
         Email,
       },
       getRequiredUrlRelations,
+      sendingStatusService,
     });
   }
 }

package/core/server/services/email-service/email-service.js

@@ -29,12 +29,15 @@ const messages = {
   retryEmailNotFailed: 'Only failed emails can be retried',
 };
 
-// Resume scanner won't pick up `submitting` rows older than this. Rows beyond the cutoff
-// are flipped to `failed` on first boot so they surface in admin UI for operator review
-// rather than being silently resumed (and sending stale newsletters to current members).
+// Resume scanner won't pick up `pending` or `submitting` rows older than this. Rows beyond
+// the cutoff are flipped to `failed` on first boot so they surface in admin UI for operator
+// review rather than being silently resumed (and sending stale newsletters to current members).
 // Override via `bulkEmail:resumeMaxAgeMs` in config.
 const DEFAULT_RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
+// Non-terminal email statuses, both of which the boot scanner recovers.
+const RESUMABLE_EMAIL_STATUSES = ['pending', 'submitting'];
+
 class EmailService {
   #batchSendingService;
   #sendingService;
@@ -223,28 +226,31 @@ class EmailService {
   }
 
   /**
-   * Boot-time scanner: resumes newsletter emails left in `submitting` after a
-   * previous container's interrupted send. Iterates sequentially; one failure
-   * does not skip others. Rows older than the configured max-age are flipped
-   * to `failed` (not resumed) so stale content does not get sent to current members.
+   * Boot-time scanner: recovers newsletter emails a previous container left without work.
+   * Two shapes, both resumed through the normal emailJob path:
+   *   - `submitting` — the send was cut off mid-flight.
+   *   - `pending` — dispatch was dropped from the in-memory job queue before the job ever
+   *     started, so no batch work exists and nothing else will ever pick the row up.
+   * Iterates sequentially; one failure does not skip others. Rows older than the configured
+   * max-age are flipped to `failed` (not resumed) so stale content does not get sent to
+   * current members.
    */
   async resumeInterruptedSends() {
     const maxAgeMs = this.#config?.get?.('bulkEmail:resumeMaxAgeMs') ?? DEFAULT_RESUME_MAX_AGE_MS;
     const cutoffIso = new Date(Date.now() - maxAgeMs).toISOString();
 
     // Stale rows: too old to safely resume. Flip to `failed` so they surface in admin UI
-    // for operator review instead of being silently left in `submitting` forever.
+    // for operator review instead of being silently stuck in their current status forever.
     const stale = await this.#models.Email.findAll({
-      filter: `status:submitting+created_at:<'${cutoffIso}'`,
+      filter: `status:[${RESUMABLE_EMAIL_STATUSES.join(',')}]+created_at:<'${cutoffIso}'`,
     });
-    const staleList = stale.models || stale;
-    for (const email of staleList) {
+    for (const email of stale.models) {
       try {
         const locked = await this.#batchSendingService.updateStatusLock(
           this.#models.Email,
           email.id,
           'failed',
-          ['submitting'],
+          [email.get('status')],
         );
         if (locked) {
           logging.warn(
@@ -257,20 +263,19 @@ class EmailService {
     }
 
     // Fresh rows: within the cutoff. Resume through the normal emailJob path.
-    const emails = await this.#models.Email.findAll({
-      filter: `status:submitting+created_at:>'${cutoffIso}'`,
+    const fresh = await this.#models.Email.findAll({
+      filter: `status:[${RESUMABLE_EMAIL_STATUSES.join(',')}]+created_at:>'${cutoffIso}'`,
     });
-    const list = emails.models || emails;
-    if (staleList.length === 0 && list.length === 0) {
+    if (stale.models.length === 0 && fresh.models.length === 0) {
       return;
     }
-    if (list.length > 0) {
+    if (fresh.models.length > 0) {
       logging.info(
-        `Email resume: found ${list.length} email(s) in submitting status within max age (${maxAgeMs}ms)`,
+        `Email resume: found ${fresh.models.length} pending or submitting email(s) within max age (${maxAgeMs}ms)`,
       );
     }
 
-    for (const email of list) {
+    for (const email of fresh.models) {
       try {
         await this.#resumeOneEmail(email);
       } catch (e) {
@@ -279,23 +284,24 @@ class EmailService {
     }
 
     logging.info(
-      `Email resume scan complete: ${staleList.length} stale email(s) flipped to failed, ${list.length} fresh email(s) rescheduled`,
+      `Email resume scan complete: ${stale.models.length} stale email(s) flipped to failed, ${fresh.models.length} fresh email(s) rescheduled`,
     );
   }
 
   async #resumeOneEmail(email) {
+    const status = email.get('status');
     const post = await email.getLazyRelation('post');
     const postStatus = post ? post.get('status') : null;
     const sendable = postStatus === 'published' || postStatus === 'sent';
 
     if (!sendable) {
       // Parent post was unpublished or deleted while the email was in flight.
-      // Can't resume — mark the email as failed so it stops showing as "submitting".
+      // Can't resume — mark the email as failed so it stops showing as unsent.
       const locked = await this.#batchSendingService.updateStatusLock(
         this.#models.Email,
         email.id,
         'failed',
-        ['submitting'],
+        [status],
       );
       if (locked) {
         logging.warn(
@@ -305,19 +311,22 @@ class EmailService {
       return;
     }
 
-    // Flip submitting -> pending so emailJob's status lock (['pending', 'failed']) admits it.
-    // If updateStatusLock returns undefined, another path raced us — just continue.
-    const locked = await this.#batchSendingService.updateStatusLock(
-      this.#models.Email,
-      email.id,
-      'pending',
-      ['submitting'],
-    );
-    if (!locked) {
-      logging.info(
-        `Email resume: ${email.id} status changed before lock could be taken — skipping`,
+    // `pending` is already what emailJob's status lock (['pending', 'failed']) admits, so
+    // only `submitting` needs flipping. If updateStatusLock returns undefined, another path
+    // raced us — leave it to whoever won.
+    if (status === 'submitting') {
+      const locked = await this.#batchSendingService.updateStatusLock(
+        this.#models.Email,
+        email.id,
+        'pending',
+        ['submitting'],
       );
-      return;
+      if (!locked) {
+        logging.info(
+          `Email resume: ${email.id} status changed before lock could be taken — skipping`,
+        );
+        return;
+      }
     }
 
     // Structured breadcrumb so post-incident timing/batch state is recoverable from logs.

package/core/server/services/email-service/sending-status-schema.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbBatchSendingRow = exports.DbEmailSendingRow = exports.StoredSendingStatus = void 0;
+const zod_1 = require("zod");
+const count_1 = require("../../lib/db-types/count");
+const date_1 = require("../../lib/db-types/date");
+exports.StoredSendingStatus = zod_1.z.enum(['pending', 'submitting', 'submitted', 'failed']);
+// Projections of tables the Bookshelf models own, not full rows, so there is no knex table
+// augmentation here: typing `emails` by these columns alone would mistype every other read.
+exports.DbEmailSendingRow = zod_1.z.object({
+    id: zod_1.z.string(),
+    status: exports.StoredSendingStatus,
+    email_count: count_1.DbCount,
+    updated_at: date_1.DbDate.nullable(),
+});
+exports.DbBatchSendingRow = zod_1.z.object({
+    status: exports.StoredSendingStatus,
+    created_at: date_1.DbDate,
+    updated_at: date_1.DbDate,
+    recipient_count: count_1.DbCount,
+});

package/core/server/services/email-service/sending-status-serializers.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEmailStatusesResponse = void 0;
+const zod_1 = require("zod");
+const case_keys_1 = require("../../lib/case-keys");
+const sending_status_1 = require("./sending-status");
+const SendingPhaseResource = zod_1.z.enum(['preparing', 'submitting']);
+const SendingResource = zod_1.z.object({
+    status: zod_1.z.enum(['preparing', 'submitting', 'submitted', 'failed']),
+    progress: zod_1.z.object({
+        completed: zod_1.z.number(),
+        total: zod_1.z.number(),
+        estimated_seconds_remaining: zod_1.z.number().nullable(),
+    }),
+    failed_during: SendingPhaseResource.optional(),
+});
+const EmailStatusResource = zod_1.z.object({
+    id: zod_1.z.string(),
+    sending: SendingResource,
+});
+const EmailStatusesResponse = zod_1.z.object({ email_statuses: zod_1.z.array(EmailStatusResource) });
+exports.toEmailStatusesResponse = sending_status_1.EmailSendingStatus.transform(({ id, sending }) => ({
+    email_statuses: [
+        {
+            id,
+            sending: {
+                status: sending.status,
+                progress: (0, case_keys_1.snakeKeys)(sending.progress),
+                ...(sending.status === 'failed' ? { failed_during: sending.failedDuring } : {}),
+            },
+        },
+    ],
+})).pipe(EmailStatusesResponse);

package/core/server/services/email-service/sending-status-service.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendingStatusService = void 0;
+const case_keys_1 = require("../../lib/case-keys");
+const sending_status_schema_1 = require("./sending-status-schema");
+const sending_status_1 = require("./sending-status");
+class SendingStatusService {
+    #knex;
+    constructor({ knex }) {
+        this.#knex = knex;
+    }
+    async statusFor(emailId) {
+        const row = await this.#knex('emails')
+            .select('id', 'status', 'email_count', 'updated_at')
+            .where('id', emailId)
+            .first();
+        if (!row) {
+            return null;
+        }
+        const email = sending_status_schema_1.DbEmailSendingRow.parse(row);
+        // A submitted email answers from its own count, and batch creation reconciles email_count
+        // to the recipient rows it built, so the batch query is skipped rather than run and ignored.
+        const batches = email.status === 'submitted' ? [] : await this.#batchesFor(emailId);
+        return {
+            id: email.id,
+            sending: (0, sending_status_1.buildSendingStatus)({
+                status: email.status,
+                recipientCount: email.email_count,
+                // The sending job saves the email when it takes its status lock, so updated_at
+                // stands in for the attempt start that Ghost does not record.
+                attemptStartedAt: email.updated_at,
+            }, batches),
+        };
+    }
+    async #batchesFor(emailId) {
+        // Correlated per-batch count stays on the batch_id index; grouping recipients by email_id scans every recipient row.
+        const recipientCount = this.#knex('email_recipients as recipient')
+            .count('*')
+            .whereRaw('recipient.batch_id = batch.id');
+        const rows = await this.#knex('email_batches as batch')
+            .select('batch.status', 'batch.created_at', 'batch.updated_at')
+            .select(recipientCount.as('recipient_count'))
+            .where('batch.email_id', emailId);
+        return rows.map((batchRow) => (0, case_keys_1.camelKeys)(sending_status_schema_1.DbBatchSendingRow.parse(batchRow)));
+    }
+}
+exports.SendingStatusService = SendingStatusService;