feat: Add sender-based routing support with backward compatibility (Fixes #145)

[EINDEX]

Summary

Adds support for routing notifications by sender address in addition to recipient address.

Backward compatible: existing configs.<recipient> direct configurations keep their recipient-based meaning.

Resolves #145

Changes

• Enhanced SimpleRouter to match sender and recipient patterns using fnmatch
• Keeps direct configs as recipient -> config with an implicit *@* sender
• Adds nested configs as sender -> recipient -> config for sender-scoped routing
• Fixes multi-recipient handling in the simple router
• Documents sender-scoped routing examples

Examples

Sender-scoped routing for any recipient:

configs:
  "unifi@domain.com":
    "*@*":
      urls:
        - pover://USER_KEY@TOKEN

Fine-grained sender and recipient routing:

configs:
  "monitoring@*":
    "alerts@mycompany.com":
      urls:
        - slack://...

Testing

• /Users/eindex/.pyenv/versions/3.12.3/bin/python -m pytest -q

Follow-up

Dotted full email config keys are handled in stacked PR EINDEX#1 for #164.

[ZzenlD]

Hey @EINDEX, I opened issue #164 because the recipient email address doesn't allow periods (e.g., foo.bar@example.com).

If you could modify the two functions below as follows, this would be possible while preserving all existing functionality:

class Sent2RecvRouter(Router):
    [...]
    async def email_to_apprise(
        self, logger: Logger, email: EmailMessage, auth_data: typ.Any, **kwargs) \
            -> typ.AsyncGenerator[AppriseNotification, None]:
        [...]
        mapping = {
            'subject': email.subject,
            'from': email.from_,
            'from_name': email.from_.partition('<')[0].strip(),
            'body': email.body,
            'to': str(rcpt.key),
            'config': rcpt.key.as_configured(),
            'type': rcpt.notify_type
        }

def _parse_sent2recv_key(logger: Logger, key: str) -> _Key:
    def fatal():
        logger.critical(
            "Invalid config key '%s'; should be a string or an email address",
            key)
        raise SystemExit(1)
    if '@' in key:
        user, domain = _parseaddrparts(key)
        if not user or not domain:
            fatal()
        return _Key(user=user, domain=domain.lower())
    if '.' in key:
        fatal()

    return _Key(user=key)

Maybe you could include this in your pull request as well 😄

Thanks for your great work.

[ZzenlD]

Hey, sorry it took me a while to test this.
Thanks for the adjustment—it works great. I have one more “request”:

Could you add the single line 'from_name': email.from_.partition('<')[0].strip(),, as shown in my last code example:

class Sent2RecvRouter(Router):
    [...]
    async def email_to_apprise(
        self, logger: Logger, email: EmailMessage, auth_data: typ.Any, **kwargs) \
            -> typ.AsyncGenerator[AppriseNotification, None]:
        [...]
        mapping = {
            'subject': email.subject,
            'from': email.from_,
            'from_name': email.from_.partition('<')[0].strip(),
            'body': email.body,
            'to': str(rcpt.key),
            'config': rcpt.key.as_configured(),
            'type': rcpt.notify_type
        }

This allows the from_name variable to be accessed in the template. Thanks :)

Let’s hope @YoRyan picks up on these changes soon, including an Apprise update.