Add Support for Custom Headers in SMTP Appender

[ppkarwasz]

Currently, the SMTP Appender does not support adding custom headers to outgoing email messages. In contrast, the HTTP Appender allows users to define custom headers using <Property> elements. Introducing similar support for the SMTP Appender would enhance feature parity across appenders and improve user experience and flexibility.

Proposed Solution

Both the HTTP and SMTP Appenders extend AbstractFilterable and already support <Property> configuration elements. In the HTTP Appender, these <Property> elements are interpreted as HTTP headers. Similarly, the SMTP Appender could treat <Property> entries as custom email headers.

Example:

<Appenders>
  <SMTP name="Email" ...>
    <Property name="X-Custom-ID" value="12345"/>
    <Property name="Reply-To" value="noreply@example.com"/>
  </SMTP>
</Appenders>

This change would preserve existing behavior while enabling greater customization for advanced email use cases.

[sidhantmourya]

Hello @ppkarwasz ,

I'd like to contribute to this enhancement.

Is this issue currently open for contribution? If so, could you please guide me on where to start in the codebase (such as which classes or modules are involved)? Also, are there any recommended steps for setting up the project locally, including running and debugging it? I'm particularly interested in any tips for working with a large codebase like this, as it's my first time contributing to a project of this scale.

Thank you.

[ppkarwasz]

Hi @sidhantmourya,

Thanks for volunteering! We really appreciate contributions — all issues are open for community help, especially since we receive more requests than we can handle on our own.

For this specific issue, here are a few pointers to get you started:

• In Log4j Core, each appender is typically split into two components: the Appender (which mostly handles configuration) and an associated AbstractManager.
• The HttpAppender, for example, accepts additional headers via a Property[] array.
• These headers are processed in HttpURLConnectionManager, where they are applied to each request.
• A similar approach is needed for SmtpAppender, particularly in its interaction with MailManager.
• One caveat: MailManager is an abstract class with two concrete implementations — one targeting Java EE and another for Jakarta EE (located in the log4j-jakarta-smtp module).

For help with building and debugging the codebase, please see our BUILDING.md guide.

Let me know if you run into any questions!

[sidhantmourya]

@ppkarwasz I'm adding custom header support to the SMTP appender similar to the HTTP appender, but need guidance on handling the javax.mail vs jakarta.mail MimeMessage types - what's the recommended way to implement applyHeaders() to work with both implementations? Should I use instanceof checks, create separate methods, or is there a better pattern?

my solution is something like this in the Abstract Class curently.

protected void applyHeaders(final Object message, final StrSubstitutor substitutor)
            throws MessagingException, NoSuchMethodException, InvocationTargetException, IllegalAccessException {
        Method setHeader = message.getClass().getMethod(
                "setHeader",
                String.class,
                String.class
        );
        for (Property header : headers)
        {
            setHeader.invoke(message, header.getName(), substitutor.replace(header.getValue()));

        }
    }

And then handle the exceptions in the implementation classes.

[ppkarwasz]

Hi @sidhantmourya,

Thanks for digging into this!

I must admit that when I introduced the Jakarta version of the SMTP appender, I only added a minimal abstraction for MailManager. In hindsight, I could have refactored more shared logic into the abstract base class. One reason I held back was that SmtpManager exposes Java EE Mail types in its public and protected methods, which we can’t remove without breaking backward compatibility.

That said, if you'd like to take on abstracting MimeMessage, feel free — it would be a useful improvement. Alternatively, you're also welcome to duplicate the logic across both MailManager implementations. The Java EE version will be removed in Log4j 3.x anyway, so code duplication is a short-term compromise.

A few quick notes on the code you shared:

setHeader.invoke(message, header.getName(), substitutor.replace(header.getValue()));

When calling MimeMessage.setHeader(), make sure the value is correctly encoded and safe. Specifically:

1. The value must be ASCII-only, per RFC 5322, section 2.2.
2. It must not contain newlines, to avoid header injection vulnerabilities.
3. It must respect the 998-character line length limit, per RFC 5322, section 2.1.1. For example, I’ve seen overly long headers cause message rejection on a Debian server running Exim with default settings.

To handle these constraints, you can use the encode and fold methods from MimeUtility.

Finally, although HttpAppender only supports property substitution, I’d personally prefer we allow full PatternLayout expressions here — just like the "Subject" field is implemented in SmtpManager.

[sidhantmourya]

Hi @ppkarwasz,
After reading through the documentation, I've updated the header handling to properly encode and fold values per RFC 5322 requirements. The current implementation uses MimeUtility to ensure ASCII-only content with proper line length limits.

for (Property header : headers)
        {
            String value = MimeUtility.fold(78, MimeUtility.encodeText(substitutor.replace(header.getValue())));
            setHeader.invoke(message, header.getName(), value);

        }

I'm now looking at how to implement PatternLayout support for headers similar to how SubjectSerializer works.

PatternLayout.java
final Serializer subjectSerializer = PatternLayout.newSerializerBuilder()
                    .setConfiguration(getConfiguration())
                    .setPattern(subject)
                    .build();

The issue is that while there's only one subject per email, there can be multiple headers each with their own potential patterns.
Looking at the SMTPAppender test case in , I see subjects can contain patterns like "%X{key}", but I'm unsure how to properly extend this to multiple headers.

@Test
    void testDelivery() {
        final String subjectKey = getClass().getName();
        final String subjectValue = "SubjectValue1";
        ThreadContext.put(subjectKey, subjectValue);
        final int smtpPort = AvailablePortFinder.getNextAvailable();
        final SmtpAppender appender = SmtpAppender.newBuilder()
                .setName("Test")
                .setTo("to@example.com")
                .setCc("cc@example.com")
                .setBcc("bcc@example.com")
                .setFrom("from@example.com")
                .setReplyTo("replyTo@example.com")
                .setSubject("Subject Pattern %X{" + subjectKey + "} %maxLen{%m}{10}")
                .setSmtpHost(HOST)
                .setSmtpPort(smtpPort)
                .setBufferSize(3)
                .build();
        assertNotNull(appender);
        assertInstanceOf(SmtpManager.class, appender.getManager());
        appender.start();
...
}

I went through the documentation and found this https://logging.apache.org/log4j/2.x/manual/pattern-layout.html#plugin-attr-header.
Are there any existing examples in the codebase of similar multi-pattern handling that I could follow?