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

The Open questions section might still contain unimplemented ideas.

Extension Point : IEmailAddressResolver

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

The IEmailAddressResolver is a fallback mechanism for determining which email address should be used to send notifications.

Purpose

Trac provides an extendible and flexible notification system, that historically has sent emails to the email address specified in the user preferences or in the CC, reporter or author fields.

Now plugins can add additional ways to find an email address for a Trac session that has no email address specified in the user preferences.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The get_address_for_session() method returns the email address for the given session or None. The parameters are:

• sid: The Trac session ID.
• authenticated: 1 if the Trac session ID is authenticated, 0 otherwise.

Examples

The following naively uses LDAP to retrieve the email address.

import ldap

from trac.core import *
from trac.notification.api import IEmailAddressResolver

class LdapEmailAddressResolver(Component):

    implements(IEmailAddressResolver)

    # IEmailAddressResolver methods
    
    def get_address_for_session(sid, authenticated):
        address = None
        ld = ldap.initialize('ldap://localhost:1390')
        ld.simple_bind_s()
        for dn, entry in ld.search_s('ou=people,dc=example,dc=com',
                                     ldap.SCOPE_SUBTREE,
                                     '(cn={0})' % sid,
                                     ['mail']):
            if 'mail' in entry:
                address = entry['mail']
        ld.unbind_s()
        return address

Available Implementations

Only trac.ticket.notification.mail.SessionEmailResolver are part of core Trac.

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

Additional Information and References

• ​epydoc
• ​API Reference
• This interface originated in ​th:AnnouncerPlugin as IAnnouncementAddressResolver.
  • DONE Renamed get_address_for_name() to get_address_for_session().
  • DONE Other distributors can not use the same interface (according to comment in ​th:AnnouncerPlugin's XmppDistributor) so this is email specific.

• Related tickets:
  • #2766 introduced the ignore_domains option after so user names that look like email addresses are recognized correctly.
  • #4372 introduced the admit_domains option so email addresses with uncommon domains are recognized correctly.

Open Questions

Integrate in email distributor?

Is this even needed? The email distributor could just contain this logic directly.

Counter-arguments:

• Plugins that for example integrate Trac with an external directory services could automatically retrieve a users email address from there using this interface.
• See next question.

Support extendible email address recognition?

Categorizing CC field entries as email addresses or session ids is surprisingly complex. In Trac various configuration options have already been added to help some corner cases (e.g. admit_domains, ignore_domains, use_short_addr). In the future, similar problems should be solvable by writing a simple plugin implementing this interface.

Would this work with the current approach? It seems this logic would have to be executed in an earlier stage. When parsing a CC field a subscriber creates session and authenticated or address values. The IEmailAddressResolver is only invoked later, on session and authenticated.

(Support for admit_domains, ignore_domains, use_short_addr and smtp_default_domain was implemented in changeset:2c5d1c0c2abb/psuter, for now without using this or any other extension point.)

Support distributors other than email?

Should this work with distributors other than email? Is email a special case? Because it is inherently complex? Or because there are complex compatibility issues with usage of raw email addresses in ticket fields? Or should other distributors support raw addresses too? How would these be recognized / differentiated? (XMPP addresses look similar to email addresses.)

Would a resolver have to know the preferred transport of a session to decide if the preferred email or XMPP address should be yielded? Or would there be separate OrderedExtensionsOptions (e.g. email_address_resolvers and xmpp_address_resolvers) in the respective distributors?

Perhaps adding a transport parameter is all that is needed.