Edgewall Software

Extension Point : IEmailDecorator


An IEmailDecorator decorates notification email, usually by adding additional email headers.


Trac provides an extendible and flexible notification system, that historically has sent emails formatted by some fixed logic.

Now plugins can implement different transports and formatters, decoupling the formatting logic from the transport implementation. IEmailDecorator allows also decoupling e.g. email title formatting and other header manipulation both from transport-neutral formatting logic and the email transport implementation.


Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The decorate_message() decorates the email message as appropriate. The parameters are:

  • event: A trac.notification.api.NotificationEvent instance describing the event about which the recipients should be notified.
  • message: An email.message.Message to decorate.
  • charset: A email.charset.Charset to use for headers.


The following example adds a custom X-Trac-Notification-Author header to emails:

from trac.core import *
from trac.notification.api import IEmailDecorator
from trac.notification.mail import set_header

class AuthorEmailDecorator(Component):


    # IEmailDecorator methods
    def decorate_message(self, event, message, charset):
        set_header(message, 'X-Trac-Notification-Author', event.author, charset)

See wiki:CookBook/Notification/Email for more examples.

Available Implementations

Additional Information and References


  • This interface originated in th:AnnouncerPlugin as IAnnouncementEmailDecorator.
  • 1.1.3: Integrated IEmailDecorator in Trac as part of this proposal (#3517)
    • Removed continuation-passing style (next_decorator()).
    • Added charset parameter.
Last modified 13 months ago Last modified on Mar 12, 2017, 10:11:03 AM
Note: See TracWiki for help on using the wiki.