This page was a draft. See TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailDecorator page now.

The Open questions section might still contain unimplemented ideas.

Extension Point : IEmailDecorator

Interface	IEmailDecorator	Since	1.1.3
Module	trac.notification	Source	api.py​

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

Purpose

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.

Usage

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.

Examples

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):

    implements(IEmailDecorator)

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

ReplyToTicketDecorator

Another example (adapted from ​a feature request) changes the reply-to address depending on the ticket id (so recipients can just reply to the emails and e.g. ​th:EmailtoTracScript can forward such replies to 10044@trac-hacks.org to ​the appropriate ticket):

from trac.core import Component, implements
from trac.config import Option
from trac.notification.api import IEmailDecorator
from trac.notification.mail import set_header

class ReplyToTicketDecorator(Component):
    """Replaces the 'Reply-To' header for tickets with a dynamic email address.

    Uses a new config option 'ticket_smtp_replyto'.
    """
    implements(IEmailDecorator)

    ticket_smtp_replyto = Option('notification', 'ticket_smtp_replyto', '__id__@localhost',
                """Reply-To address for ticket notification emails.

                   ` __id__` is replaced with the ticket id.""")

    def decorate_message(self, event, message, charset):
        if event.realm == 'ticket':
            replyto = self.ticket_email_replyto.replace('__id__', str(event.target.id))
            set_header(message, 'Reply-To', replyto, charset)

Available Implementations

The following implementations are part of core Trac:

• trac.ticket.notification.mail.AlwaysEmailDecorator: Implements smtp_always_cc and smtp_always_bcc configuration options.

Various other resolvers might be part of ​th:AnnouncerPlugin.

Additional Information and References

• ​epydoc
• ​API Reference
• This interface originated in ​th:AnnouncerPlugin as IAnnouncementEmailDecorator.
  • DONE Removed continuation-passing style (next_decorator()).
  • DONE Added charset parameter.

Open Questions

Make AlwaysEmailDecorator a subscriber instead?

​For Announcer it was suggested that the always CC / BCC configuration options should be implemented in a subscriber instead, as in Announcer decorators can not influence email recipients.

The proposed changes​ instead fix this deficiency of decorators.

Are there any other reasons to use a subscriber?