{{{#!box important
This page was a draft. See [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailDecorator] page now.

The [#OpenQuestions Open questions] section might still contain unimplemented ideas.
}}}

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

||'''Interface'''||''IEmailDecorator''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.3#IEmailDecorator 1.1.3]||
||'''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.
* `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 ==

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 ==

 * [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()`).
   * DONE Added `charset` parameter.

== Open Questions

=== Make !AlwaysEmailDecorator a subscriber instead?

[th:comment:3:ticket:10676 For Announcer it was suggested] that the ''always CC / BCC'' configuration options should be implemented in a [wiki:INotificationSubscriber subscriber] instead, as in Announcer decorators can not influence email recipients.

The [source:psuter/trac/notification/mail.py@cefae24eeddf:243-244,247-250#L233 proposed changes] instead fix this deficiency of decorators.

Are there any other reasons to use a subscriber?