== Extension Point : ''IEmailAddressResolver'' ==

||'''Interface'''||''IEmailAddressResolver''||'''Since'''||[wiki:TracDev/ApiChanges/1.1#IEmailAddressResolver 1.1.3]||
||'''Module'''||''trac.notification''||'''Source'''||[source:trunk/trac/notification/api.py#/IEmailAddressResolver api.py]||

The ''IEmailAddressResolver'' is a fallback mechanism for determining which email address should be used to send [TracNotification 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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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.

{{{#!python
import ldap

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

class LdapEmailAddressResolver(Component):

    implements(IEmailAddressResolver)

    # IEmailAddressResolver methods
    
    def get_address_for_session(self, 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=%s)' % sid,
                                     ['mail']):
            if 'mail' in entry:
                address = entry['mail']
        ld.unbind_s()
        return address
}}}

== Available Implementations ==

* [source:trunk/trac/notification/mail.py#/SessionEmailResolver trac.notification.mail.SessionEmailResolver]

== Additional Information and References ==

 * [apiref:trac.notification.api.IEmailAddressResolver-class epydoc]
 * [apidoc:api/trac_notification#trac.notification.api.IEmailAddressResolver API Reference]
 * 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.

=== History
 * This interface originated in th:AnnouncerPlugin as `IAnnouncementAddressResolver`.
 * [wiki:TracDev/ApiChanges/1.1#IEmailAddressResolver 1.1.3]: Integrated `IEmailAddressResolver` in Trac as part of [wiki:TracDev/Proposals/AdvancedNotification this proposal] (#3517)
   * Renamed `get_address_for_name()` to `get_address_for_session()`.