Add Mailgun tag for member welcome emails (#26590)

ref
https://linear.app/ghost/issue/NY-1027/add-a-tag-to-welcome-emails-in-mailgun-to-make-filtering-easier

### Motivation
- Make welcome emails easier to filter in Mailgun by attaching a
dedicated tag to those sends.
- Allow callers to pass per-message Mailgun tags so specific email types
can be identified in logs and analytics.

### Description
- Added `MEMBER_WELCOME_EMAIL_TAG = 'member-welcome-email'` and exported
it from `member-welcome-emails/constants.js`.
- Passed that tag from `MemberWelcomeEmailService` into the mail payload
via a new `mailgunTags` message field.
- Extended `GhostMailer` to accept `mailgunTags` in `send()` and merge
them with default tags via the updated `getTags(additionalTags = [])`
implementation, with deduplication.
- Added/updated tests to assert that the `mailgunTags` are propagated
from the welcome-email flow and merged into Mailgun `o:tag` values.

### Manual testing

I tested this out locally with Mailgun, and confirmed that I can see the
tags coming through in the logs:
<img width="1952" height="99" alt="Screenshot 2026-02-25 at 15 15 58"
src="https://github.com/user-attachments/assets/b3cd3ec6-85c0-405c-98b5-32f2f8f03a79"
/>

Author: cmraible

ghost/core/core/server/services/mail/ghost-mailer.js

@@ -2,6 +2,7 @@
 // Handles sending email for Ghost
 const _ = require('lodash');
 const config = require('../../../shared/config');
+const logging = require('@tryghost/logging');
 const errors = require('@tryghost/errors');
 const tpl = require('@tryghost/tpl');
 const settingsCache = require('../../../shared/settings-cache');
@@ -18,6 +19,7 @@ const messages = {
 };
 const EmailAddressParser = require('../email-address/email-address-parser');
 const DEFAULT_TAGS = ['ghost-email', 'transactional-email'];
+const MAX_MAILGUN_TAGS = 10;
 
 function getDomain() {
     const domain = urlUtils.urlFor('home', true).match(new RegExp('^https?://([^/:?#]+)(?:[/:?#]|$)', 'i'));
@@ -62,11 +64,14 @@ function getFromAddress(requestedFromAddress, requestedReplyToAddress) {
 function createMessage(message) {
     const encoding = 'base64';
     const generateTextFromHTML = !message.forceTextContent;
+    const cleanMessage = {...message};
+    delete cleanMessage.tags;
+    delete cleanMessage.forceTextContent;
 
     const addresses = getFromAddress(message.from, message.replyTo);
 
     return {
-        ...message,
+        ...cleanMessage,
         ...addresses,
         generateTextFromHTML,
         encoding,
@@ -116,6 +121,7 @@ module.exports = class GhostMailer {
      * @param {string} [message.replyTo]
      * @param {string} [message.from] - sender email address
      * @param {string} [message.text] - text version of this message
+     * @param {string[]} [message.tags] - optional additional Mailgun tags
      * @param {boolean} [message.forceTextContent] - maps to generateTextFromHTML nodemailer option
      * which is: "if set to true uses HTML to generate plain text body part from the HTML if the text is not defined"
      * (ref: https://github.com/nodemailer/nodemailer/tree/da2f1d278f91b4262e940c0b37638e7027184b1d#e-mail-message-fields)
@@ -131,7 +137,7 @@ module.exports = class GhostMailer {
 
         const messageToSend = createMessage(message);
         if (this.state.usingMailgun) {
-            const tags = this.getTags();
+            const tags = this.getTags(message.tags);
             if (tags.length > 0) {
                 messageToSend['o:tag'] = tags;
             }
@@ -195,14 +201,38 @@ module.exports = class GhostMailer {
         return tpl(messages.messageSent);
     }
 
-    getTags() {
+    /**
+     * Builds the Mailgun tag list from defaults, site tag, and optional extra tags.
+     * @param {string[]} [additionalTags]
+     * @returns {string[]}
+     */
+    getTags(additionalTags = []) {
         const tagList = [...DEFAULT_TAGS];
 
         const siteId = config.get('hostSettings:siteId');
         if (siteId) {
             tagList.push(`blog-${siteId}`);
         }
 
-        return tagList;
+        if (Array.isArray(additionalTags) && additionalTags.length > 0) {
+            const cleanedTags = additionalTags
+                .filter(tag => typeof tag === 'string')
+                .map(tag => tag.trim().toLowerCase())
+                .filter(tag => tag.length > 0);
+
+            tagList.push(...cleanedTags);
+        }
+
+        const uniqueTags = [...new Set(tagList)];
+
+        if (uniqueTags.length > MAX_MAILGUN_TAGS) {
+            const keptTags = uniqueTags.slice(0, MAX_MAILGUN_TAGS);
+
+            logging.warn(`[MAIL] Mailgun tag count exceeded ${MAX_MAILGUN_TAGS}; truncating tags from ${uniqueTags.length} to ${MAX_MAILGUN_TAGS}.`);
+
+            return keptTags;
+        }
+
+        return uniqueTags;
     }
 };

ghost/core/core/server/services/member-welcome-emails/constants.js

@@ -5,6 +5,8 @@ const MEMBER_WELCOME_EMAIL_SLUGS = {
     paid: 'member-welcome-email-paid'
 };
 
+const MEMBER_WELCOME_EMAIL_TAG = 'member-welcome-email';
+
 const MESSAGES = {
     NO_MEMBER_WELCOME_EMAIL: 'No member welcome email found',
     INVALID_LEXICAL_STRUCTURE: 'Member welcome email has invalid content structure',
@@ -16,6 +18,7 @@ const MESSAGES = {
 
 module.exports = {
     MEMBER_WELCOME_EMAIL_LOG_KEY,
+    MEMBER_WELCOME_EMAIL_TAG,
     MEMBER_WELCOME_EMAIL_SLUGS,
     MESSAGES
 };

ghost/core/core/server/services/member-welcome-emails/service.js

@@ -9,7 +9,7 @@ const mail = require('../mail');
 // @ts-expect-error type checker has trouble with the dynamic exporting in models
 const {AutomatedEmail, Newsletter} = require('../../models');
 const MemberWelcomeEmailRenderer = require('./member-welcome-email-renderer');
-const {MEMBER_WELCOME_EMAIL_LOG_KEY, MEMBER_WELCOME_EMAIL_SLUGS, MESSAGES} = require('./constants');
+const {MEMBER_WELCOME_EMAIL_LOG_KEY, MEMBER_WELCOME_EMAIL_TAG, MEMBER_WELCOME_EMAIL_SLUGS, MESSAGES} = require('./constants');
 
 class MemberWelcomeEmailService {
     #mailer;
@@ -157,6 +157,7 @@ class MemberWelcomeEmailService {
             html,
             text,
             forceTextContent: true,
+            tags: [MEMBER_WELCOME_EMAIL_TAG],
             ...senderOptions
         });
     }

ghost/core/test/e2e-api/admin/__snapshots__/members.test.js.snap

@@ -2034,7 +2034,6 @@ If you did not make this request, you can simply delete this message. You will n
 exports[`Members API Can add and send a signup confirmation email 5: [metadata 1] 1`] = `
 Object {
   "encoding": "base64",
-  "forceTextContent": true,
   "from": "\\"Ghost's Test Site\\" <noreply@127.0.0.1>",
   "generateTextFromHTML": false,
   "headers": Object {

ghost/core/test/e2e-api/admin/__snapshots__/newsletters.test.js.snap

@@ -2179,7 +2179,6 @@ Object {
 exports[`Newsletters API Managed email with custom sending domain Can set newsletter reply-to to any email address with required verification 3: [metadata 1] 1`] = `
 Object {
   "encoding": "base64",
-  "forceTextContent": true,
   "from": "\\"Ghost\\" <noreply@sendingdomain.com>",
   "generateTextFromHTML": false,
   "headers": Object {
@@ -3382,7 +3381,6 @@ Object {
 exports[`Newsletters API Managed email without custom sending domain Can set newsletter reply-to to any email address with required verification 3: [metadata 1] 1`] = `
 Object {
   "encoding": "base64",
-  "forceTextContent": true,
   "from": "\\"Ghost\\" <default@email.com>",
   "generateTextFromHTML": false,
   "headers": Object {

ghost/core/test/integration/services/member-welcome-emails.test.js

@@ -345,6 +345,7 @@ describe('Member Welcome Emails Integration', function () {
             sinon.assert.calledOnce(mailService.GhostMailer.prototype.send);
             const sendCall = mailService.GhostMailer.prototype.send.firstCall;
             assert.equal(sendCall.args[0].to, memberEmail);
+            assert.deepEqual(sendCall.args[0].tags, ['member-welcome-email']);
         });
 
         it('uses configured sender and reply-to when sending member welcome email', async function () {

ghost/core/test/unit/server/services/mail/ghost-mailer.test.js

@@ -4,6 +4,7 @@ const mail = require('../../../../../core/server/services/mail');
 const settingsCache = require('../../../../../core/shared/settings-cache');
 const configUtils = require('../../../../utils/config-utils');
 const urlUtils = require('../../../../../core/shared/url-utils');
+const logging = require('@tryghost/logging');
 let mailer;
 const assert = require('node:assert/strict');
 const {assertExists} = require('../../../../utils/assertions');
@@ -400,6 +401,74 @@ describe('Mail: Ghostmailer', function () {
             assert(!sentMessage['o:tag'].includes('blog-123123'));
         });
 
+        it('should include custom tags passed by the caller', async function () {
+            configUtils.set({
+                hostSettings: {siteId: '123123'}
+            });
+            sandbox.stub(settingsCache, 'get').withArgs('email_track_opens').returns(false);
+
+            mailer = new mail.GhostMailer();
+            mailer.state.usingMailgun = true;
+            const sendMailSpy = sandbox.stub(mailer.transport, 'sendMail').resolves({});
+
+            await mailer.send({
+                to: 'user@example.com',
+                subject: 'test',
+                html: 'content',
+                tags: ['member-welcome-email']
+            });
+
+            const sentMessage = sendMailSpy.firstCall.args[0];
+            assert(sentMessage['o:tag'].includes('transactional-email'));
+            assert(sentMessage['o:tag'].includes('member-welcome-email'));
+            assert.equal(sentMessage.tags, undefined);
+            assert.equal(sentMessage.forceTextContent, undefined);
+        });
+
+        it('should truncate tags to Mailgun maximum and log warning', async function () {
+            configUtils.set({
+                hostSettings: {siteId: '123123'}
+            });
+            sandbox.stub(settingsCache, 'get').withArgs('email_track_opens').returns(false);
+            const warnStub = sandbox.stub(logging, 'warn');
+
+            mailer = new mail.GhostMailer();
+            mailer.state.usingMailgun = true;
+            const sendMailSpy = sandbox.stub(mailer.transport, 'sendMail').resolves({});
+
+            await mailer.send({
+                to: 'user@example.com',
+                subject: 'test',
+                html: 'content',
+                tags: [
+                    'tag-1',
+                    'tag-2',
+                    'tag-3',
+                    'tag-4',
+                    'tag-5',
+                    'tag-6',
+                    'tag-7',
+                    'tag-8',
+                    'tag-9'
+                ]
+            });
+
+            const sentMessage = sendMailSpy.firstCall.args[0];
+            assert.deepEqual(sentMessage['o:tag'], [
+                'ghost-email',
+                'transactional-email',
+                'blog-123123',
+                'tag-1',
+                'tag-2',
+                'tag-3',
+                'tag-4',
+                'tag-5',
+                'tag-6',
+                'tag-7'
+            ]);
+            sinon.assert.called(warnStub);
+        });
+
         it('should not add tag when not using Mailgun transport', async function () {
             configUtils.set({
                 hostSettings: {siteId: '999999'}

ghost/core/test/unit/server/services/settings/__snapshots__/settings-bread-service.test.js.snap

@@ -189,7 +189,6 @@ exports[`UNIT > Settings BREAD Service: edit setting members_support_address tri
 exports[`UNIT > Settings BREAD Service: edit setting members_support_address triggers email verification 3: [metadata 1] 1`] = `
 Object {
   "encoding": "base64",
-  "forceTextContent": true,
   "from": "\\"Ghost at 127.0.0.1\\" <noreply@example.com>",
   "generateTextFromHTML": false,
   "headers": Object {