amsdal_mail 0.1.0__py3-none-any.whl

amsdal_mail/Third-Party Materials - AMSDAL Dependencies - License Notices.md

@@ -0,0 +1,29 @@
+# Third-Party Materials - AMSDAL Dependencies - License Notices
+
+## **pydantic v2.12 or later**
+
+### [https://github.com/pydantic/pydantic](https://github.com/pydantic/pydantic)
+
+### **MIT License**
+
+The MIT License (MIT)
+
+Copyright (c) 2017 to present Pydantic Services Inc. and individual contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amsdal_mail/__about__.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

amsdal_mail/__init__.py

@@ -0,0 +1,164 @@
+"""AMSDAL Mail - Universal email integration for AMSDAL Framework."""
+
+from amsdal_mail.backends import get_connection
+from amsdal_mail.events import EmailTrackingContext
+from amsdal_mail.events import EmailTrackingEvent
+from amsdal_mail.events import TrackingEventType
+from amsdal_mail.exceptions import ConfigurationError
+from amsdal_mail.exceptions import EmailConnectionError
+from amsdal_mail.exceptions import EmailError
+from amsdal_mail.exceptions import SendError
+from amsdal_mail.message import Attachment
+from amsdal_mail.message import EmailMessage
+from amsdal_mail.settings import mail_settings
+from amsdal_mail.status import RecipientStatus
+from amsdal_mail.status import SendStatus
+from amsdal_mail.status import SendStatusType
+
+__all__ = [
+    'Attachment',
+    'ConfigurationError',
+    'EmailConnectionError',
+    'EmailError',
+    'EmailMessage',
+    'EmailTrackingContext',
+    'EmailTrackingEvent',
+    'RecipientStatus',
+    'SendError',
+    'SendStatus',
+    'SendStatusType',
+    'TrackingEventType',
+    'asend_mail',
+    'get_connection',
+    'mail_settings',
+    'send_mail',
+]
+
+
+def send_mail(
+    subject: str,
+    message: str,
+    from_email: str,
+    recipient_list: list[str] | str,
+    *,
+    fail_silently: bool = False,
+    html_message: str | None = None,
+    connection=None,
+    **kwargs,
+) -> SendStatus:
+    """
+    Send a single email message.
+
+    This is a convenience function for sending simple emails. For more control,
+    use EmailMessage and get_connection() directly.
+
+    Args:
+        subject: Email subject line
+        message: Plain text body
+        from_email: Sender email address
+        recipient_list: List of recipient email addresses (or single string)
+        fail_silently: If True, suppress exceptions and return empty SendStatus on failure
+        html_message: HTML version of body (optional)
+        connection: Reuse existing connection (optional)
+        **kwargs: Additional arguments passed to EmailMessage
+
+    Returns:
+        SendStatus object with message IDs, statuses, and ESP response
+
+    Raises:
+        SendError: If sending fails and fail_silently is False
+
+    Examples:
+        >>> status = send_mail(
+        ...     'Hello',
+        ...     'This is a test email',
+        ...     'sender@example.com',
+        ...     ['recipient@example.com'],
+        ... )
+        >>> status.message_id
+        'msg-123'
+        >>> status.is_success
+        True
+    """
+    # Get or create connection
+    connection = connection or get_connection(fail_silently=fail_silently)
+
+    # Normalize recipient_list to list
+    if isinstance(recipient_list, str):
+        recipient_list = [recipient_list]
+
+    # Create email message
+    mail = EmailMessage(
+        subject=subject,
+        body=message,
+        from_email=from_email,
+        to=recipient_list,
+        html_body=html_message,
+        **kwargs,
+    )
+
+    # Send message
+    return connection.send_messages([mail])
+
+
+async def asend_mail(
+    subject: str,
+    message: str,
+    from_email: str,
+    recipient_list: list[str] | str,
+    *,
+    fail_silently: bool = False,
+    html_message: str | None = None,
+    connection=None,
+    **kwargs,
+) -> SendStatus:
+    """
+    Send a single email message asynchronously.
+
+    Async version of send_mail(). See send_mail() for parameter documentation.
+
+    Args:
+        subject: Email subject line
+        message: Plain text body
+        from_email: Sender email address
+        recipient_list: List of recipient email addresses (or single string)
+        fail_silently: If True, suppress exceptions and return empty SendStatus on failure
+        html_message: HTML version of body (optional)
+        connection: Reuse existing connection (optional)
+        **kwargs: Additional arguments passed to EmailMessage
+
+    Returns:
+        SendStatus object with message IDs, statuses, and ESP response
+
+    Raises:
+        SendError: If sending fails and fail_silently is False
+
+    Examples:
+        >>> status = await asend_mail(
+        ...     'Hello',
+        ...     'This is a test email',
+        ...     'sender@example.com',
+        ...     ['recipient@example.com'],
+        ... )
+        >>> status.message_id
+        'msg-123'
+    """
+    # Get or create connection
+    connection = connection or get_connection(fail_silently=fail_silently)
+
+    # Normalize recipient_list to list
+    if isinstance(recipient_list, str):
+        recipient_list = [recipient_list]
+
+    # Create email message
+    mail = EmailMessage(
+        subject=subject,
+        body=message,
+        from_email=from_email,
+        to=recipient_list,
+        html_body=html_message,
+        **kwargs,
+    )
+
+    # Send message asynchronously
+    return await connection.asend_messages([mail])

amsdal_mail/app.py

@@ -0,0 +1,36 @@
+"""AMSDAL integration for amsdal_mail plugin."""
+
+from amsdal.contrib.app_config import AppConfig
+
+
+class MailAppConfig(AppConfig):
+    """
+    AMSDAL plugin configuration for amsdal_mail.
+
+    Register this in your AMSDAL application settings:
+        AMSDAL_CONTRIBS = 'amsdal_mail.app.MailAppConfig'
+    """
+
+    name = 'amsdal_mail'
+    verbose_name = 'AMSDAL Email Integration'
+
+    def on_setup(self) -> None:
+        """Called when the plugin is loaded by AMSDAL."""
+        from amsdal_mail.settings import mail_settings
+
+        if mail_settings.WEBHOOK_ENABLED:
+            self._setup_webhooks()
+
+    @staticmethod
+    def _setup_webhooks() -> None:
+        from amsdal_server.apps.common.events.server import RouterSetupEvent  # type: ignore[import-not-found]
+        from amsdal_utils.events import EventBus
+
+        from amsdal_mail.settings import mail_settings
+        from amsdal_mail.webhooks.listener import WebhookRouterListener
+        from amsdal_mail.webhooks.registry import WebhookRegistry
+        from amsdal_mail.webhooks.ses import SESWebhookParser
+
+        WebhookRegistry.register('ses', SESWebhookParser(secret=mail_settings.WEBHOOK_SES_SECRET))
+
+        EventBus.subscribe(RouterSetupEvent, WebhookRouterListener)

amsdal_mail/backends/__init__.py

@@ -0,0 +1,103 @@
+"""Backend registry and connection utilities."""
+
+import importlib
+import os
+from typing import Any
+
+from amsdal_mail.backends.base import BaseEmailBackend
+
+# Registry of available backends
+BACKENDS: dict[str, str] = {
+    'console': 'amsdal_mail.backends.console.ConsoleBackend',
+    'dummy': 'amsdal_mail.backends.dummy.DummyBackend',
+    'ses': 'amsdal_mail.backends.ses.SESBackend',
+    'smtp': 'amsdal_mail.backends.smtp.SMTPBackend',
+}
+
+
+def import_string(dotted_path: str) -> Any:
+    """
+    Import a class from a dotted module path.
+
+    Args:
+        dotted_path: Full dotted path to class (e.g., 'package.module.ClassName')
+
+    Returns:
+        The imported class
+
+    Raises:
+        ImportError: If the module or class cannot be imported
+    """
+    try:
+        module_path, class_name = dotted_path.rsplit('.', 1)
+    except ValueError as e:
+        msg = f"'{dotted_path}' doesn't look like a module path"
+        raise ImportError(msg) from e
+
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as e:
+        msg = f"Module '{module_path}' could not be imported"
+        raise ImportError(msg) from e
+
+    try:
+        return getattr(module, class_name)
+    except AttributeError as e:
+        msg = f"Module '{module_path}' does not define a '{class_name}' class"
+        raise ImportError(msg) from e
+
+
+def get_connection(
+    backend: str | None = None,
+    *,
+    fail_silently: bool = False,
+    **kwargs: Any,
+) -> BaseEmailBackend:
+    """
+    Load an email backend and return an instance.
+
+    Args:
+        backend: Backend name (from BACKENDS registry) or full dotted path.
+                 If None, uses AMSDAL_EMAIL_BACKEND environment variable.
+                 Defaults to 'console' if not specified.
+        fail_silently: If True, suppress exceptions in send operations
+        **kwargs: Backend-specific configuration options
+
+    Returns:
+        An instance of the specified backend
+
+    Raises:
+        ImportError: If the backend cannot be imported
+        ConfigurationError: If the backend is misconfigured
+
+    Examples:
+        >>> # Use registered backend name
+        >>> conn = get_connection('smtp', host='smtp.gmail.com', port=587)
+
+        >>> # Use full dotted path
+        >>> conn = get_connection('myapp.backends.CustomBackend')
+
+        >>> # Use environment variable
+        >>> os.environ['AMSDAL_EMAIL_BACKEND'] = 'smtp'
+        >>> conn = get_connection()
+    """
+    # Resolve backend name
+    if backend is None:
+        backend = os.environ.get('AMSDAL_EMAIL_BACKEND', 'console')
+
+    # Check if it's a registered backend name
+    if backend in BACKENDS:
+        backend = BACKENDS[backend]
+
+    # Import and instantiate the backend
+    backend_cls = import_string(backend)
+
+    return backend_cls(fail_silently=fail_silently, **kwargs)
+
+
+__all__ = [
+    'BACKENDS',
+    'BaseEmailBackend',
+    'get_connection',
+    'import_string',
+]

amsdal_mail/backends/base.py

@@ -0,0 +1,87 @@
+"""Base email backend interface."""
+
+from abc import ABC
+from abc import abstractmethod
+from typing import TYPE_CHECKING
+from typing import Any
+
+if TYPE_CHECKING:
+    from amsdal_mail.message import EmailMessage
+    from amsdal_mail.status import SendStatus
+
+
+class BaseEmailBackend(ABC):
+    """Abstract base class for all email backends."""
+
+    def __init__(self, *, fail_silently: bool = False, **kwargs: Any) -> None:
+        """
+        Initialize the email backend.
+
+        Args:
+            fail_silently: If True, suppress exceptions and return 0 for failed sends
+            **kwargs: Backend-specific configuration options
+        """
+        self.fail_silently = fail_silently
+        self.extra_kwargs = kwargs
+
+    def open(self) -> None:
+        """
+        Open a network connection to the email service
+
+        This method is called automatically when using the backend as a context manager.
+        Override this method if your backend needs to establish a persistent connection.
+        """
+        pass
+
+    def close(self) -> None:
+        """
+        Close the network connection to the email service.
+
+        This method is called automatically when exiting the context manager.
+        Override this method if your backend needs to clean up resources.
+        """
+        pass
+
+    def __enter__(self) -> 'BaseEmailBackend':
+        """Enter context manager - open connection."""
+        self.open()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        """Exit context manager - close connection."""
+        self.close()
+
+    @abstractmethod
+    def send_messages(self, email_messages: list['EmailMessage']) -> 'SendStatus':
+        """
+        Send one or more email messages.
+
+        Args:
+            email_messages: List of EmailMessage instances to send
+
+        Returns:
+            SendStatus object with message IDs, statuses, and ESP response data
+
+        Raises:
+            SendError: If sending fails and fail_silently is False
+        """
+        msg = 'Subclasses must implement send_messages()'
+        raise NotImplementedError(msg)
+
+    async def asend_messages(self, email_messages: list['EmailMessage']) -> 'SendStatus':
+        """
+        Send one or more email messages asynchronously.
+
+        Default implementation falls back to synchronous send_messages().
+        Override this method to provide true async implementation.
+
+        Args:
+            email_messages: List of EmailMessage instances to send
+
+        Returns:
+            SendStatus object with message IDs, statuses, and ESP response data
+
+        Raises:
+            SendError: If sending fails and fail_silently is False
+        """
+        return self.send_messages(email_messages)

amsdal_mail/backends/console.py

@@ -0,0 +1,91 @@
+"""Console email backend - writes emails to stdout."""
+
+import sys
+from typing import IO
+from typing import Any
+
+from amsdal_mail.backends.base import BaseEmailBackend
+from amsdal_mail.message import EmailMessage
+from amsdal_mail.status import RecipientStatus
+from amsdal_mail.status import SendStatus
+
+
+class ConsoleBackend(BaseEmailBackend):
+    """
+    Email backend that writes messages to a stream (default: stdout).
+
+    Useful for development and debugging.
+    """
+
+    def __init__(self, stream: IO[str] | None = None, **kwargs: Any) -> None:
+        """
+        Initialize the console backend.
+
+        Args:
+            stream: Output stream (defaults to sys.stdout)
+            **kwargs: Additional backend options (passed to parent)
+        """
+        super().__init__(**kwargs)
+        self.stream = stream or sys.stdout
+
+    def send_messages(self, email_messages: list[EmailMessage]) -> SendStatus:
+        """
+        Write email messages to the stream.
+
+        Args:
+            email_messages: List of EmailMessage instances to output
+
+        Returns:
+            SendStatus with 'sent' status for all recipients
+        """
+        status = SendStatus()
+        recipients = {}
+
+        for message in email_messages:
+            self.stream.write('-' * 79 + '\n')
+            self.stream.write(f'Subject: {message.subject}\n')
+            self.stream.write(f'From: {message.from_email}\n')
+            self.stream.write(f'To: {", ".join(str(addr) for addr in message.to)}\n')
+
+            if message.cc:
+                self.stream.write(f'Cc: {", ".join(str(addr) for addr in message.cc)}\n')
+
+            if message.bcc:
+                self.stream.write(f'Bcc: {", ".join(str(addr) for addr in message.bcc)}\n')
+
+            if message.reply_to:
+                self.stream.write(f'Reply-To: {", ".join(str(addr) for addr in message.reply_to)}\n')
+
+            if message.headers:
+                for key, value in message.headers.items():
+                    self.stream.write(f'{key}: {value}\n')
+
+            self.stream.write('\n')
+
+            if message.html_body:
+                self.stream.write('Content-Type: multipart/alternative\n')
+                self.stream.write('\n--- Plain Text ---\n')
+                self.stream.write(message.body)
+                self.stream.write('\n\n--- HTML ---\n')
+                self.stream.write(message.html_body)
+            else:
+                self.stream.write(message.body)
+
+            if message.attachments:
+                self.stream.write('\n\n--- Attachments ---\n')
+                for attachment in message.attachments:
+                    size_kb = len(attachment.content) / 1024
+                    self.stream.write(f'- {attachment.filename} ({attachment.mimetype}, {size_kb:.1f} KB)\n')
+
+            self.stream.write('\n' + '-' * 79 + '\n\n')
+
+            # Add recipient status (console backend always succeeds)
+            for recipient in message.recipients():
+                recipients[recipient] = RecipientStatus(
+                    message_id=None,  # Console backend doesn't generate message IDs
+                    status='sent',
+                )
+
+        self.stream.flush()
+        status.set_recipient_status(recipients)
+        return status

amsdal_mail/backends/dummy.py

@@ -0,0 +1,56 @@
+"""Dummy email backend - does not send emails."""
+
+from typing import Any
+
+from amsdal_mail.backends.base import BaseEmailBackend
+from amsdal_mail.message import EmailMessage
+from amsdal_mail.status import RecipientStatus
+from amsdal_mail.status import SendStatus
+
+
+class DummyBackend(BaseEmailBackend):
+    """
+    Email backend that does not actually send emails.
+
+    Useful for testing - pretends to send messages successfully but does nothing.
+    Optionally stores messages for inspection during tests.
+    """
+
+    def __init__(self, *, store_messages: bool = False, **kwargs: Any) -> None:
+        """
+        Initialize the dummy backend.
+
+        Args:
+            store_messages: If True, store sent messages in self.messages list
+            **kwargs: Additional backend options (passed to parent)
+        """
+        super().__init__(**kwargs)
+        self.store_messages = store_messages
+        self.messages: list[EmailMessage] = []
+
+    def send_messages(self, email_messages: list[EmailMessage]) -> SendStatus:
+        """
+        Pretend to send email messages.
+
+        Args:
+            email_messages: List of EmailMessage instances to "send"
+
+        Returns:
+            SendStatus with 'sent' status for all recipients
+        """
+        if self.store_messages:
+            self.messages.extend(email_messages)
+
+        status = SendStatus()
+        recipients = {}
+
+        # Mark all recipients as sent (but don't actually send)
+        for message in email_messages:
+            for recipient in message.recipients():
+                recipients[recipient] = RecipientStatus(
+                    message_id=None,  # Dummy backend doesn't generate message IDs
+                    status='sent',
+                )
+
+        status.set_recipient_status(recipients)
+        return status