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

||'''Interface'''||''IEmailDecorator''||'''Since'''||[wiki:TracDev/ApiChanges/1.1#IEmailDecorator 1.1.3]||
||'''Module'''||''trac.notification''||'''Source'''||[source:trunk/trac/notification/api.py#/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:trac.notification.api.INotificationDistributor transports] and [wiki:trac.notification.api.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.
* `charset`: A `email.charset.Charset` to use for headers.

== 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, charset):
        set_header(message, 'X-Trac-Notification-Author', event.author, charset)
}}}

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

== Available Implementations ==

* [source:trunk/trac/notification/mail.py#/AlwaysEmailDecorator trac.notification.mail.AlwaysEmailDecorator]: Implements `smtp_always_cc` and `smtp_always_bcc` configuration options.

== Additional Information and References ==

 * [apiref:trac.notification.api.IEmailDecorator-class epydoc]
 * [apidoc:api/trac_notification#trac.notification.api.IEmailDecorator API Reference]

=== History
 * This interface originated in th:AnnouncerPlugin as `IAnnouncementEmailDecorator`.
 * [wiki:TracDev/ApiChanges/1.1#IEmailDecorator 1.1.3]: Integrated `IEmailDecorator` in Trac as part of [wiki:TracDev/Proposals/AdvancedNotification this proposal] (#3517)
   * Removed continuation-passing style (`next_decorator()`).
   * Added `charset` parameter.