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

||'''Interface'''||''IEmailDecorator''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.3#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)
}}}

=== !ReplyToTicketDecorator

Another example (adapted from [th:comment:4:ticket:10044 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 [th:ticket:10044 the appropriate ticket]):
{{{#!python
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 ==

* [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.3#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.