ghost 6.55.0 → 6.57.0

package/core/server/services/adapter-manager/utils.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {createRequire} from 'node:module';
+import errors from '@tryghost/errors';
 import type {AdapterConstructor} from "./types";
 import type {ConfigInstance} from '../../../shared/config/loader';
 
@@ -122,6 +123,62 @@ export function resolveAdapterExport(moduleExport: unknown): AdapterConstructor
     return null;
 }
 
+/**
+* Locate and load an adapter constructor by type and class name, trying each of
+* `pathsToAdapters` in order. Shared by the adapter manager and by
+* bin/validate-adapters.ts, so a name resolves — and fails — identically at build
+* time and at runtime.
+*/
+export function loadAdapterClass(
+    adapterType: string,
+    adapterClassName: string,
+    pathsToAdapters: string[],
+    loadAdapterFromPath: (path: string) => unknown
+): AdapterConstructor {
+    for (const pathToAdapters of pathsToAdapters) {
+        let pathToAdapter = path.join(pathToAdapters, adapterType, adapterClassName);
+        if (pathToAdapters === '') {
+            // We are loading from node_modules, we can remove the `adapterType` prefix
+            pathToAdapter = path.join(pathToAdapters, adapterClassName);
+        }
+        // An adapter directory may be a full module with its own
+        // package.json, in which case this resolves the `exports` entry
+        // point; otherwise the path passes through unchanged.
+        const moduleToLoad = resolveAdapterEntryPoint(pathToAdapter);
+
+        try {
+            const Adapter = resolveAdapterExport(loadAdapterFromPath(moduleToLoad));
+            if (Adapter) {
+                return Adapter;
+            }
+        } catch (err) {
+            // Catch runtime errors
+            if (!(err instanceof Error) || (err as NodeJS.ErrnoException).code !== 'MODULE_NOT_FOUND') {
+                throw new errors.IncorrectUsageError({err: err as Error});
+            }
+
+            // Catch missing dependencies BUT NOT missing adapter.
+            // Only check the first line — Node appends a "Require stack"
+            // that includes the adapter's own path, which would false-positive.
+            const firstLine = err.message.split('\n')[0];
+            if (!firstLine.includes(pathToAdapter)) {
+                // Name the unresolved module so the error is actionable, e.g.
+                // "Cannot find module 'superagent'" -> 'superagent'.
+                const missingMatch = /Cannot find module '([^']+)'/.exec(firstLine);
+                const missingModule = missingMatch ? ` '${missingMatch[1]}'` : '';
+                throw new errors.IncorrectUsageError({
+                    message: `You are missing a dependency${missingModule} in your adapter ${pathToAdapter}`,
+                    err: err as Error
+                });
+            }
+        }
+    }
+
+    throw new errors.IncorrectUsageError({
+        message: `Unable to find ${adapterType} adapter ${adapterClassName} in ${pathsToAdapters}.`
+    });
+}
+
 function getSchedulingConfig(config: ConfigInstance) {
     const adapterConfig = config.get('adapters:scheduling');
     if (!adapterConfig) {

package/core/server/services/audience-feedback/audience-feedback-controller.js

@@ -50,7 +50,7 @@ class AudienceFeedbackController {
             // Load the full post (with tags/authors) rather than passing an
             // id-only resource: the URL service needs status to apply the
             // published base filter and tags/authors to evaluate filtered
-            // routes — the lazy backend rejects a bare {id} as thin.
+            // routes — the URL service reports a bare {id} as thin.
             const post = await this.#repository.getPostById(postId, {withRelated: ['tags', 'authors']});
             const target = post
                 ? this.#audienceFeedbackService.buildLink(uuid, post, score, key)

package/core/server/services/audience-feedback/audience-feedback-service.js

@@ -24,7 +24,7 @@ class AudienceFeedbackService {
      */
     buildLink(uuid, post, score, key) {
         const postData = toPlain(post);
-        let postUrl = this.#urlService.facade.getUrlForResource({...postData, type: 'posts'}, {absolute: true});
+        let postUrl = this.#urlService.getUrlForResource({...postData, type: 'posts'}, {absolute: true});
 
         if (postUrl.match(/\/404\//)) {
             postUrl = this.#baseURL;
@@ -36,7 +36,7 @@ class AudienceFeedbackService {
      * Feedback link for a post that no longer exists. Goes straight to the
      * home page — the same destination buildLink picks when the URL service
      * has no URL for the post — without asking the URL service: an id-only
-     * resource can't be routed (the lazy backend rejects it as thin).
+     * resource can't be routed (the URL service reports it as thin).
      *
      * @param {string} uuid
      * @param {string} postId

package/core/server/services/automations/automations-repository.ts

@@ -90,6 +90,7 @@ export type AutomatedEmailEvents = {
 
 export type RecordEmailSentOptions = Readonly<{
     automationActionRevisionId: string;
+    automationRunStepId: string;
     mailgunMessageId?: string;
     memberEmail: string;
     memberId: string;
@@ -203,11 +204,12 @@ export interface AutomationsRepository {
         eventsByAutomatedEmailRecipientId: ReadonlyDeep<Map<string, AutomatedEmailEvents>>
     ): Promise<void>;
     /**
-     * Track the first click for an automated email recipient.
+     * Record the first click timestamp for the automated email recipient identified by a run step.
      *
      */
     trackEmailClicked(options: {
         automationActionRevisionId: string;
+        automationRunStepId: string;
         memberId: string;
         clickedAt: Readonly<Date>;
     }, transactionOptions?: {

package/core/server/services/automations/database-automations-repository.js

@@ -135,6 +135,7 @@ function createDatabaseAutomationsRepository({ knex, fakeWaitHoursMultiplier })
                     member_email: options.memberEmail,
                     member_name: options.memberName,
                     automation_action_revision_id: options.automationActionRevisionId,
+                    automation_run_step_id: options.automationRunStepId,
                     ...(options.mailgunMessageId ? { mailgun_message_id: options.mailgunMessageId } : {}),
                     track_clicks: options.trackClicks,
                     track_opens: options.trackOpens,
@@ -157,6 +158,13 @@ function createDatabaseAutomationsRepository({ knex, fakeWaitHoursMultiplier })
                 return;
             }
             await knex.transaction(async (trx) => {
+                const revisionIds = new Set();
+                for (const { openedAt, automationActionRevisionId } of eventsByAutomatedEmailRecipientId.values()) {
+                    if (openedAt) {
+                        revisionIds.add(automationActionRevisionId);
+                    }
+                }
+                const orderedRevisionIds = await lockActionRevisions(trx, revisionIds);
                 const notYetOpened = await lockNotYetOpened(trx, eventsByAutomatedEmailRecipientId);
                 const newOpensPerRevision = new Map();
                 for (const [id, { deliveredAt, openedAt, automationActionRevisionId }] of eventsByAutomatedEmailRecipientId) {
@@ -177,10 +185,11 @@ function createDatabaseAutomationsRepository({ knex, fakeWaitHoursMultiplier })
                         newOpensPerRevision.set(automationActionRevisionId, (newOpensPerRevision.get(automationActionRevisionId) ?? 0) + 1);
                     }
                 }
-                // Keep lock acquisition order consistent across concurrent transactions to avoid deadlocks.
-                const revisions = [...newOpensPerRevision.entries()]
-                    .sort(([left], [right]) => left.localeCompare(right));
-                for (const [id, opens] of revisions) {
+                for (const id of orderedRevisionIds) {
+                    const opens = newOpensPerRevision.get(id);
+                    if (!opens) {
+                        continue;
+                    }
                     await trx('automation_action_revisions')
                         .where({ id })
                         .update({
@@ -189,24 +198,17 @@ function createDatabaseAutomationsRepository({ knex, fakeWaitHoursMultiplier })
                 }
             });
         },
-        async trackEmailClicked({ automationActionRevisionId, memberId, clickedAt }, { transacting } = {}) {
+        async trackEmailClicked({ automationActionRevisionId, automationRunStepId, memberId, clickedAt }, { transacting } = {}) {
             const trackClick = async (trx) => {
-                // Match recordEmailSent's lock order to avoid deadlocks.
-                await trx('automation_action_revisions')
-                    .select('id')
-                    .where({ id: automationActionRevisionId })
-                    .forUpdate()
-                    .first();
+                await lockActionRevisions(trx, [automationActionRevisionId]);
                 const recipient = await trx('automated_email_recipients')
                     .select('id', 'clicked_at')
                     .where({
                     automation_action_revision_id: automationActionRevisionId,
+                    automation_run_step_id: automationRunStepId,
                     member_id: memberId,
                     track_clicks: true
                 })
-                    .where('created_at', '<=', (0, database_date_1.toDatabaseDate)(clickedAt))
-                    .orderBy('created_at', 'desc')
-                    .orderBy('id', 'desc')
                     .forUpdate()
                     .first();
                 if (!recipient || recipient.clicked_at !== null) {
@@ -233,6 +235,23 @@ function createDatabaseAutomationsRepository({ knex, fakeWaitHoursMultiplier })
         }
     };
 }
+/**
+ * Lock revisions before recipients because inserting a recipient takes a shared
+ * foreign-key lock on its revision. Updating that revision later can deadlock
+ * with another transaction that has already locked the revision and is waiting
+ * for the recipient. Keep multi-revision lock acquisition deterministic.
+ */
+async function lockActionRevisions(trx, revisionIds) {
+    const sortedRevisionIds = [...new Set(revisionIds)]
+        .sort((left, right) => left.localeCompare(right));
+    if (sortedRevisionIds.length > 0) {
+        await trx('automation_action_revisions')
+            .select('id')
+            .whereIn('id', sortedRevisionIds)
+            .forUpdate();
+    }
+    return sortedRevisionIds;
+}
 /**
  * Which of these recipients have yet to open, and so should count towards their
  * revision's open count. Locks them for the transaction, so a worker racing on

package/core/server/services/automations/database-automations-repository.ts

@@ -276,6 +276,7 @@ export function createDatabaseAutomationsRepository({
                     member_email: options.memberEmail,
                     member_name: options.memberName,
                     automation_action_revision_id: options.automationActionRevisionId,
+                    automation_run_step_id: options.automationRunStepId,
                     ...(options.mailgunMessageId ? {mailgun_message_id: options.mailgunMessageId} : {}),
                     track_clicks: options.trackClicks,
                     track_opens: options.trackOpens,
@@ -301,6 +302,15 @@ export function createDatabaseAutomationsRepository({
             }
 
             await knex.transaction(async (trx) => {
+                const revisionIds = new Set<string>();
+                for (const {openedAt, automationActionRevisionId} of eventsByAutomatedEmailRecipientId.values()) {
+                    if (openedAt) {
+                        revisionIds.add(automationActionRevisionId);
+                    }
+                }
+
+                const orderedRevisionIds = await lockActionRevisions(trx, revisionIds);
+
                 const notYetOpened = await lockNotYetOpened(trx, eventsByAutomatedEmailRecipientId);
                 const newOpensPerRevision = new Map<string, number>();
 
@@ -327,11 +337,11 @@ export function createDatabaseAutomationsRepository({
                     }
                 }
 
-                // Keep lock acquisition order consistent across concurrent transactions to avoid deadlocks.
-                const revisions = [...newOpensPerRevision.entries()]
-                    .sort(([left], [right]) => left.localeCompare(right));
-
-                for (const [id, opens] of revisions) {
+                for (const id of orderedRevisionIds) {
+                    const opens = newOpensPerRevision.get(id);
+                    if (!opens) {
+                        continue;
+                    }
                     await trx('automation_action_revisions')
                         .where({id})
                         .update({
@@ -341,25 +351,18 @@ export function createDatabaseAutomationsRepository({
             });
         },
 
-        async trackEmailClicked({automationActionRevisionId, memberId, clickedAt}, {transacting} = {}) {
+        async trackEmailClicked({automationActionRevisionId, automationRunStepId, memberId, clickedAt}, {transacting} = {}) {
             const trackClick = async (trx: Knex.Transaction) => {
-                // Match recordEmailSent's lock order to avoid deadlocks.
-                await trx('automation_action_revisions')
-                    .select('id')
-                    .where({id: automationActionRevisionId})
-                    .forUpdate()
-                    .first();
+                await lockActionRevisions(trx, [automationActionRevisionId]);
 
                 const recipient = await trx('automated_email_recipients')
                     .select('id', 'clicked_at')
                     .where({
                         automation_action_revision_id: automationActionRevisionId,
+                        automation_run_step_id: automationRunStepId,
                         member_id: memberId,
                         track_clicks: true
                     })
-                    .where('created_at', '<=', toDatabaseDate(clickedAt))
-                    .orderBy('created_at', 'desc')
-                    .orderBy('id', 'desc')
                     .forUpdate()
                     .first();
 
@@ -394,6 +397,29 @@ export function createDatabaseAutomationsRepository({
     };
 }
 
+/**
+ * Lock revisions before recipients because inserting a recipient takes a shared
+ * foreign-key lock on its revision. Updating that revision later can deadlock
+ * with another transaction that has already locked the revision and is waiting
+ * for the recipient. Keep multi-revision lock acquisition deterministic.
+ */
+async function lockActionRevisions(
+    trx: Knex.Transaction,
+    revisionIds: Iterable<string>
+): Promise<string[]> {
+    const sortedRevisionIds = [...new Set(revisionIds)]
+        .sort((left, right) => left.localeCompare(right));
+
+    if (sortedRevisionIds.length > 0) {
+        await trx('automation_action_revisions')
+            .select('id')
+            .whereIn('id', sortedRevisionIds)
+            .forUpdate();
+    }
+
+    return sortedRevisionIds;
+}
+
 /**
  * Which of these recipients have yet to open, and so should count towards their
  * revision's open count. Locks them for the transaction, so a worker racing on

package/core/server/services/automations/get-scheduler-idempotency-key.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSchedulerIdempotencyKey = getSchedulerIdempotencyKey;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+function getSchedulerIdempotencyKey(date, url) {
+    const hash = node_crypto_1.default.createHash('sha256');
+    hash.update(date.toISOString());
+    hash.update(url.href);
+    return `ghost-automations-${hash.digest('hex')}`;
+}

package/core/server/services/automations/get-scheduler-idempotency-key.ts

@@ -0,0 +1,8 @@
+import crypto from 'node:crypto';
+
+export function getSchedulerIdempotencyKey(date: Readonly<Date>, url: Readonly<URL>): string {
+    const hash = crypto.createHash('sha256');
+    hash.update(date.toISOString());
+    hash.update(url.href);
+    return `ghost-automations-${hash.digest('hex')}`;
+}

package/core/server/services/automations/poll.js

@@ -129,7 +129,8 @@ const processStep = async ({ automationsApi, memberWelcomeEmailService, schedule
                     memberStatus,
                     trackOpens,
                     trackClicks,
-                    automationActionRevisionId: step.automation_action_revision_id
+                    automationActionRevisionId: step.automation_action_revision_id,
+                    automationRunStepId: step.id
                 });
                 const mailgunMessageId = (0, mailgun_message_id_1.getMailgunMessageId)(sendResult);
                 // Only Mailgun sends can produce open events for automation emails
@@ -137,6 +138,7 @@ const processStep = async ({ automationsApi, memberWelcomeEmailService, schedule
                 try {
                     await automationsApi.recordEmailSent({
                         automationActionRevisionId: step.automation_action_revision_id,
+                        automationRunStepId: step.id,
                         ...(mailgunMessageId ? { mailgunMessageId } : {}),
                         memberEmail: member.get('email'),
                         memberId: step.member_id,

package/core/server/services/automations/poll.ts

@@ -28,6 +28,7 @@ type MemberWelcomeEmailService = {
             trackOpens: boolean;
             trackClicks: boolean;
             automationActionRevisionId: string;
+            automationRunStepId: string;
         }) => Promise<unknown>;
     };
 };
@@ -202,7 +203,8 @@ const processStep = async ({
                 memberStatus,
                 trackOpens,
                 trackClicks,
-                automationActionRevisionId: step.automation_action_revision_id
+                automationActionRevisionId: step.automation_action_revision_id,
+                automationRunStepId: step.id
             });
             const mailgunMessageId = getMailgunMessageId(sendResult);
             // Only Mailgun sends can produce open events for automation emails
@@ -210,6 +212,7 @@ const processStep = async ({
             try {
                 await automationsApi.recordEmailSent({
                     automationActionRevisionId: step.automation_action_revision_id,
+                    automationRunStepId: step.id,
                     ...(mailgunMessageId ? {mailgunMessageId} : {}),
                     memberEmail: member.get('email'),
                     memberId: step.member_id,

package/core/server/services/automations/service.js

@@ -41,6 +41,7 @@ const strict_1 = __importDefault(require("node:assert/strict"));
 const one_at_a_time_1 = require("../../../shared/one-at-a-time");
 const poll_1 = require("./poll");
 const automationsApi = __importStar(require("./automations-api"));
+const get_scheduler_idempotency_key_1 = require("./get-scheduler-idempotency-key");
 const promises_1 = require("node:timers/promises");
 const soonest_timer_1 = require("../../lib/soonest-timer");
 const scheduler_poll_time_1 = require("./scheduler-poll-time");
@@ -101,20 +102,23 @@ class AutomationsService {
                 schedulerAdapter.schedule({
                     time: schedulerPollTime.getTime(),
                     url: url.toString(),
-                    extra: { httpMethod: 'PUT' }
+                    extra: {
+                        httpMethod: 'PUT',
+                        idempotencyKey: (0, get_scheduler_idempotency_key_1.getSchedulerIdempotencyKey)(date, url)
+                    }
                 });
             }
             catch (err) {
                 logging.error({ event: { name: 'automations.enqueue-poll.error' }, err, at: date.toISOString() }, 'Failed to enqueue automations poll');
             }
         };
-        domainEvents.subscribe(StartAutomationsPollEvent, (0, one_at_a_time_1.oneAtATime)(async () => (0, poll_1.poll)({
+        domainEvents.subscribe(StartAutomationsPollEvent, (0, one_at_a_time_1.oneAtATime)(() => (0, poll_1.poll)({
             automationsApi,
             memberWelcomeEmailService,
             scheduleAutomationEmailAnalyticsJob,
             enqueueAnotherPollAt: enqueuePollAt
         })));
-        domainEvents.subscribe(StartAutomationsPollEvent, (0, one_at_a_time_1.oneAtATime)(async () => welcomeEmailAutomationPoll({
+        domainEvents.subscribe(StartAutomationsPollEvent, (0, one_at_a_time_1.oneAtATime)(() => welcomeEmailAutomationPoll({
             memberWelcomeEmailService,
             enqueueAnotherPollAt: enqueuePollAt
         })));

package/core/server/services/automations/service.ts

@@ -6,6 +6,7 @@ import type DomainEvents from '@tryghost/domain-events';
 import {oneAtATime} from '../../../shared/one-at-a-time';
 import {poll} from './poll';
 import * as automationsApi from './automations-api';
+import {getSchedulerIdempotencyKey} from './get-scheduler-idempotency-key';
 import {setImmediate as flushEventLoop} from 'node:timers/promises';
 import {SoonestTimer} from '../../lib/soonest-timer';
 import {getSchedulerPollTime} from './scheduler-poll-time';
@@ -85,21 +86,24 @@ export class AutomationsService {
                 schedulerAdapter.schedule({
                     time: schedulerPollTime.getTime(),
                     url: url.toString(),
-                    extra: {httpMethod: 'PUT'}
+                    extra: {
+                        httpMethod: 'PUT',
+                        idempotencyKey: getSchedulerIdempotencyKey(date, url)
+                    }
                 });
             } catch (err) {
                 logging.error({event: {name: 'automations.enqueue-poll.error'}, err, at: date.toISOString()}, 'Failed to enqueue automations poll');
             }
         };
 
-        domainEvents.subscribe(StartAutomationsPollEvent, oneAtATime(async () => poll({
+        domainEvents.subscribe(StartAutomationsPollEvent, oneAtATime(() => poll({
             automationsApi,
             memberWelcomeEmailService,
             scheduleAutomationEmailAnalyticsJob,
             enqueueAnotherPollAt: enqueuePollAt
         })));
 
-        domainEvents.subscribe(StartAutomationsPollEvent, oneAtATime(async () => welcomeEmailAutomationPoll({
+        domainEvents.subscribe(StartAutomationsPollEvent, oneAtATime(() => welcomeEmailAutomationPoll({
             memberWelcomeEmailService,
             enqueueAnotherPollAt: enqueuePollAt
         })));

package/core/server/services/comments/comments-service-emails.js

@@ -29,7 +29,7 @@ class CommentsServiceEmails {
         // Comments live on pages as well as posts; the URL service routes by
         // the passed type, so a page typed 'posts' resolves to /404/.
         const routerType = postData.type === 'page' ? 'pages' : 'posts';
-        const baseUrl = this.urlService.facade.getUrlForResource({...postData, type: routerType}, {absolute: true});
+        const baseUrl = this.urlService.getUrlForResource({...postData, type: routerType}, {absolute: true});
         return `${baseUrl}#ghost-comments-${commentId}`;
     }
 

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

@@ -473,7 +473,7 @@ class CommentsService {
      * @param {AdminBrowseAllOptions} options
      */
     async getAdminAllComments({includeNested, filter, mongoTransformer, reportCount, order, page, limit}) {
-        const postUrlRelations = this.urlService.facade.getRequiredRelations().map(relation => `post.${relation}`);
+        const postUrlRelations = this.urlService.getRequiredRelations().map(relation => `post.${relation}`);
         const withRelated = ['member', 'post', ...postUrlRelations, 'count.replies', 'count.direct_replies', 'count.likes', 'count.dislikes', 'count.net_score', 'count.reports', 'in_reply_to', 'parent'];
 
         return await this.models.Comment.findPage({

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

@@ -4,7 +4,7 @@ const config = require('../../../shared/config');
 const domainEvents = require('@tryghost/domain-events');
 /** @import {PrometheusClient} from '@tryghost/prometheus-metrics' */
 /** @import {BatchEventProcessor} from './batch-event-processor' */
-/** @import {JobNames, CursorSeed} from './email-analytics-service' */
+/** @import {JobNames, CursorSeed, EmailAnalyticsFetchResult} from './email-analytics-service' */
 
 class EmailAnalyticsServiceWrapper {
     /** @type {string} */ #logName;
@@ -74,7 +74,7 @@ class EmailAnalyticsServiceWrapper {
     /**
      * Log comprehensive job completion with timing metrics
      * @param {string} jobType - Type of job (e.g., 'latest-opened', 'latest', 'missing', 'scheduled')
-     * @param {object} fetchResult - The fetch result from EmailAnalyticsService
+     * @param {EmailAnalyticsFetchResult} fetchResult - The fetch result from EmailAnalyticsService
      * @param {number} totalDurationMs - Total duration in milliseconds
      */
     _logJobCompletion(jobType, fetchResult, totalDurationMs) {
@@ -158,6 +158,11 @@ class EmailAnalyticsServiceWrapper {
         return fetchResult.eventCount;
     }
 
+    /**
+     * @param {object} options
+     * @param {number} options.maxEvents
+     * @returns {Promise<number>} The number of scheduled events fetched
+     */
     async fetchScheduled({maxEvents}) {
         if (maxEvents < 300) {
             return 0;
@@ -227,6 +232,10 @@ class EmailAnalyticsServiceWrapper {
         this.#fetching = false;
     }
 
+    /**
+     * @param {string} reason
+     * @returns {void}
+     */
     _restartFetch(reason) {
         this.#fetching = false;
         logging.info(`${this.#logPrefix} Restarting fetch due to ${reason}`);

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

@@ -372,7 +372,7 @@ module.exports = class EmailAnalyticsService {
      * @param {EmailAnalyticsEvent[]} [options.eventTypes] - Array of event types to fetch. If not provided, Mailgun will return all event types.
      * @returns {Promise<EmailAnalyticsFetchResult>} Fetch results with timing metrics
      */
-    async #fetchEvents(fetchData, {begin, end, maxEvents = Infinity, eventTypes = null}) {
+    async #fetchEvents(fetchData, {begin, end, maxEvents = Infinity, eventTypes}) {
         // Start where we left of, or the last stored event in the database, or start 30 minutes ago if we have nothing available
         // Store that we started fetching
         fetchData.running = true;

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

@@ -31,7 +31,7 @@ class EmailServiceWrapper {
 
         const {Post, Newsletter, Email, EmailBatch, EmailRecipient, Member} = require('../../models');
         const urlService = require('../url');
-        const getRequiredUrlRelations = () => urlService.facade.getRequiredRelations();
+        const getRequiredUrlRelations = () => urlService.getRequiredRelations();
         const MailgunClient = require('../lib/mailgun-client');
         const configService = require('../../../shared/config');
         const settingsCache = require('../../../shared/settings-cache');
@@ -75,6 +75,7 @@ class EmailServiceWrapper {
 
         const mailgunEmailProvider = new MailgunEmailProvider({
             mailgunClient,
+            config: configService,
             errorHandler
         });
 

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

@@ -2,6 +2,11 @@ const logging = require('@tryghost/logging');
 const errors = require('@tryghost/errors');
 const debug = require('@tryghost/debug')('email-service:mailgun-provider-service');
 
+/**
+ * @typedef {object} Config
+ * @prop {(key: string) => unknown} get
+ */
+
 /**
  * @typedef {object} Recipient
  * @prop {string} email
@@ -29,18 +34,22 @@ const debug = require('@tryghost/debug')('email-service:mailgun-provider-service
 
 class MailgunEmailProvider {
     #mailgunClient;
+    #config;
     #errorHandler;
 
     /**
      * @param {object} dependencies
      * @param {import('../lib/mailgun-client')} dependencies.mailgunClient - mailgun client to send emails
+     * @param {Config} dependencies.config
      * @param {Function} [dependencies.errorHandler] - custom error handler for logging exceptions
      */
     constructor({
         mailgunClient,
+        config,
         errorHandler
     }) {
         this.#mailgunClient = mailgunClient;
+        this.#config = config;
         this.#errorHandler = errorHandler;
     }
 
@@ -108,12 +117,18 @@ class MailgunEmailProvider {
                 plaintext,
                 from,
                 replyTo,
+                tags: ['bulk-email'],
                 domainOverride,
                 id: emailId,
                 track_opens: !!options.openTrackingEnabled,
                 track_clicks: !!options.clickTrackingEnabled
             };
 
+            const mailgunTagFromConfig = this.#config.get('bulkEmail:mailgun:tag');
+            if (typeof mailgunTagFromConfig === 'string' && mailgunTagFromConfig.length > 0) {
+                messageData.tags.push(mailgunTagFromConfig);
+            }
+
             if (options.deliveryTime && options.deliveryTime instanceof Date) {
                 messageData.deliveryTime = options.deliveryTime;
             }

package/core/server/services/gift-links/CONTEXT.md

@@ -0,0 +1,9 @@
+# Gift Links
+
+Gift Links covers shareable access to individual protected posts and pages without creating a membership.
+
+## Language
+
+**Gift Link**:
+A revocable link that grants its holder access to one protected post or page. It does not create or redeem a gift subscription.
+_Avoid_: Redemption link, gift-subscription link