== Extension Point : ''IEmailDecorator'' ==

||'''Interface'''||''IEmailDecorator''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.2#IEmailDecorator 1.1.2]||
||'''Module'''||''trac.notification''||'''Source'''||[source:psuter/trac/notification/api.py@advanced-notification-mail-distribution#/IEmailDecorator api.py]||

An ''IEmailDecorator'' decorates [TracNotification 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 [wiki:INotificationDistributor transports] and [wiki:INotificationFormatter 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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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.

== Examples ==

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

{{{#!python
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):
        set_header(message, 'X-Trac-Notification-Author', event.author)
}}}

== Available Implementations ==

The following implementations are part of core Trac:
* `trac.ticket.notification.mail.AlwaysEmailDecorator`: Implements `email_always_cc` and `email_always_bcc` configuration options.

Various other resolvers might be part of th:AnnouncerPlugin.

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.notification.api.IEmailDecorator-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_notification.html#trac.notification.api.IEmailDecorator API Reference]
 * This interface originated in th:AnnouncerPlugin as `IAnnouncementEmailDecorator`.
   * DONE Removed continuation-passing style (`next_decorator()`).