How to add custom X-TAGS header to digest emails for external email analytics (Netcore)?

emonunix · September 10, 2025, 8:19pm

Hello everyone,

I’m a self-hosted Discourse user and I’m looking for a way to add a custom header, specifically X-TAGS, to our outgoing emails. The goal is to integrate with our email service provider (Netcore Email API) for better analytics and tracking. We want to be able to tag certain types of emails, like the weekly digest, for a more granular view of our email engagement.

Problem:

I need to add a header like X-TAGS: Digest to all the emails that are sent out as a digest. This header is for internal tracking and will be stripped by the email provider before delivery, so it won’t be visible to the end user.

What I’ve already explored:

Site Settings: I’ve looked through the /admin/site_settings/category/email page and found the email custom headers setting. However, it seems to add a static header to all emails. I’m unsure if it’s possible to make this dynamic or to apply it only to a specific type of email (like the digest).
Existing Forum Topics: I’ve searched the Discourse Meta forums and found some discussions about custom headers, but they mostly focus on adding topic tags to the email subject line or for user-side filtering (e.g., in Gmail), not for external email analytics. There doesn’t seem to be a straightforward, officially documented way to do this.

My questions are:

Is there a built-in method or a specific site setting that I’m overlooking that would allow me to add a custom header like X-TAGS specifically to digest emails?
If not, is this a feature that could be accomplished with a custom plugin?
Would modifying the core code be the only solution, and if so, could you point me in the right direction (e.g., which files to look at)?

Any guidance or suggestions would be greatly appreciated. Thank you in advance for your help!

selase · September 12, 2025, 2:31pm

No, this isn’t supported out of the box, aside from the email custom headers site setting which applies globally to all outgoing emails.

Yes, a custom plugin would the best approach here.

The current flow for digest emails, is as follows:

github.com/discourse/discourse

app/jobs/scheduled/enqueue_digest_emails.rb

d82fcb8af


      
          def execute(args)
            return if SiteSetting.disable_emails == "yes"
            return if SiteSetting.disable_digest_emails?
            return if SiteSetting.private_email?
          
            target_user_ids.each do |user_id|
              ::Jobs.enqueue(:user_email, type: "digest", user_id: user_id)
            end
          end

github.com/discourse/discourse

app/jobs/regular/user_email.rb

d82fcb8af

# frozen_string_literal: true

module Jobs
  # Asynchronously send an email to a user
  class UserEmail < ::Jobs::Base
    include Skippable

    sidekiq_options queue: "low"

    sidekiq_retry_in do |count, exception|
      # retry in an hour when SMTP server is busy
      # or use default sidekiq retry formula. returning
      # nil/0 will trigger the default sidekiq
      # retry formula
      #
      # See https://github.com/mperham/sidekiq/blob/3330df0ee37cfd3e0cd3ef01e3e66b584b99d488/lib/sidekiq/job_retry.rb#L216-L234
      case exception.wrapped
      when Net::SMTPServerBusy
        return 1.hour + (rand(30) * (count + 1))
      end

This file has been truncated. show original

github.com/discourse/discourse

app/mailers/user_notifications.rb

d82fcb8af


      
          def digest(user, opts = {})
            build_summary_for(user)
            @unsubscribe_key = UnsubscribeKey.create_key_for(@user, UnsubscribeKey::DIGEST_TYPE)
          
            @since = opts[:since].presence
            @since ||= [user.last_seen_at, user.user_stat&.digest_attempted_at, 1.month.ago].compact.max
          
            # Fetch some topics and posts to show
            digest_opts = {
              limit: SiteSetting.digest_topics + SiteSetting.digest_other_topics,
              top_order: true,
            }
            topics_for_digest = Topic.for_digest(user, @since, digest_opts)
            if topics_for_digest.empty? && !user.user_option.try(:include_tl0_in_digests)
              # Find some topics from new users that are at least 24 hours old
              topics_for_digest =
                Topic.for_digest(user, @since, digest_opts.merge(include_tl0: true)).where(
                  "topics.created_at < ?",
                  24.hours.ago,
                )

This file has been truncated. show original

github.com/discourse/discourse

lib/email/build_email_helper.rb

d82fcb8af

# frozen_string_literal: true

module Email
  module BuildEmailHelper
    def build_email(*builder_args)
      builder = Email::MessageBuilder.new(*builder_args)
      headers(builder.header_args) if builder.header_args.present?
      mail(builder.build_args).tap do |message|
        if message && h = builder.html_part
          message.html_part = h
        end
      end
    end
  end
end

github.com/discourse/discourse

lib/email/message_builder.rb

d82fcb8af

# frozen_string_literal: true

# Builds a Mail::Message we can use for sending. Optionally supports using a template
# for the body and subject
module Email
  class MessageBuilder
    attr_reader :template_args, :reply_by_email_key

    ALLOW_REPLY_BY_EMAIL_HEADER = "X-Discourse-Allow-Reply-By-Email"
    INSTRUCTIONS_SEPARATOR = "---\n"

    def initialize(to, opts = nil)
      @to = to
      @opts = opts || {}
      @template_args = {
        site_name: SiteSetting.title,
        email_prefix: SiteSetting.email_prefix.presence || SiteSetting.title,
        base_url: Discourse.base_url,
        user_preferences_url: "#{Discourse.base_url}/my/preferences",
        hostname: Discourse.current_hostname,

This file has been truncated. show original

A plugin could hook into the message building process (Email::MessageBuilder) and inject(preferably via a modifier) your custom header conditionally, only for digests.

Topic		Replies	Views
Customs email headers and/or subjects tags Feature	7	2714	January 8, 2022
Add headers to all outgoing emails Installation	2	784	October 23, 2020
How to show tags in the digest email? Support activity-summary	0	334	June 23, 2021
Email: mail headers should have tags in them Feature	2	839	August 16, 2014
Force topics into email digest via tags? Feature activity-summary	1	484	July 20, 2021

How to add custom X-TAGS header to digest emails for external email analytics (Netcore)?

Related topics