amsdal_mail 0.1.0__py3-none-any.whl

amsdal_mail/status.py

@@ -0,0 +1,189 @@
+"""Email sending status tracking."""
+
+from typing import Any
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+# Send status constants (normalized across all ESP backends)
+SendStatusType = Literal[
+    'sent',      # ESP has sent the message (may or may not be delivered yet)
+    'queued',    # ESP will try to send the message later
+    'invalid',   # Recipient email address is not valid
+    'rejected',  # Recipient is blacklisted or rejected by ESP
+    'failed',    # Send attempt failed for some other reason
+    'unknown',   # Status could not be determined
+]
+
+
+class RecipientStatus(BaseModel):
+    """
+    Status information for a single recipient.
+
+    Tracks the ESP message ID and send status for an individual recipient.
+    """
+
+    message_id: str | None = Field(
+        default=None,
+        description='ESP-assigned message ID for this recipient (None if send failed)',
+    )
+    status: SendStatusType | None = Field(
+        default=None,
+        description='Send status for this recipient (None if not yet sent to ESP)',
+    )
+
+
+class SendStatus(BaseModel):
+    """
+    Complete status information for sent email message(s).
+
+    Contains aggregated status across all recipients, per-recipient details,
+    and raw ESP response data.
+
+    Attributes:
+        message_id: ESP message ID(s). Single string if all recipients share same ID,
+                   set of strings if different IDs, or None if send failed.
+        status: Set of send statuses across all recipients.
+        recipients: Per-recipient status information, keyed by email address.
+        esp_response: Raw response from ESP API (for debugging/ESP-specific features).
+    """
+
+    message_id: str | set[str] | None = Field(
+        default=None,
+        description='ESP message ID(s) - single ID, set of IDs, or None',
+    )
+    status: set[SendStatusType] | None = Field(
+        default=None,
+        description='Set of send statuses across all recipients',
+    )
+    recipients: dict[str, RecipientStatus] = Field(
+        default_factory=dict,
+        description='Per-recipient status information (email -> RecipientStatus)',
+    )
+    esp_response: Any = Field(
+        default=None,
+        description='Raw ESP API response (non-portable, for debugging)',
+    )
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def set_recipient_status(self, recipients: dict[str, RecipientStatus]) -> None:
+        """
+        Update recipient statuses and derive aggregated message_id and status.
+
+        This method updates the recipients dictionary and automatically computes
+        the aggregated message_id and status fields based on all recipients.
+
+        Args:
+            recipients: Dictionary of email -> RecipientStatus to add/update
+
+        Example:
+            >>> status = SendStatus()
+            >>> status.set_recipient_status({
+            ...     'user@example.com': RecipientStatus(
+            ...         message_id='msg-123',
+            ...         status='sent'
+            ...     )
+            ... })
+            >>> status.message_id
+            'msg-123'
+            >>> status.status
+            {'sent'}
+        """
+        # Update recipients dict
+        self.recipients.update(recipients)
+
+        # Collect unique message IDs
+        message_ids = {r.message_id for r in self.recipients.values() if r.message_id}
+
+        if len(message_ids) == 0:
+            self.message_id = None
+        elif len(message_ids) == 1:
+            # Single message ID - simplify to string
+            self.message_id = message_ids.pop()
+        else:
+            # Multiple message IDs - keep as set
+            self.message_id = message_ids
+
+        # Collect unique statuses
+        statuses = {r.status for r in self.recipients.values() if r.status}
+        self.status = statuses if statuses else None
+
+    @property
+    def is_success(self) -> bool:
+        """
+        Check if all recipients were successfully sent or queued.
+
+        Returns:
+            True if all recipients have status 'sent' or 'queued', False otherwise.
+
+        Example:
+            >>> status = SendStatus(status={'sent', 'queued'})
+            >>> status.is_success
+            True
+            >>> status = SendStatus(status={'sent', 'failed'})
+            >>> status.is_success
+            False
+        """
+        if not self.status:
+            return False
+        return self.status.issubset({'sent', 'queued'})
+
+    @property
+    def has_failures(self) -> bool:
+        """
+        Check if any recipients failed to send.
+
+        Returns:
+            True if any recipient has status 'failed', 'rejected', or 'invalid'.
+
+        Example:
+            >>> status = SendStatus(status={'sent', 'failed'})
+            >>> status.has_failures
+            True
+        """
+        if not self.status:
+            return False
+        return bool(self.status.intersection({'failed', 'rejected', 'invalid'}))
+
+    def get_failed_recipients(self) -> list[str]:
+        """
+        Get list of email addresses that failed to send.
+
+        Returns:
+            List of email addresses with failed/rejected/invalid status.
+
+        Example:
+            >>> status = SendStatus(recipients={
+            ...     'good@example.com': RecipientStatus(status='sent'),
+            ...     'bad@example.com': RecipientStatus(status='failed'),
+            ... })
+            >>> status.get_failed_recipients()
+            ['bad@example.com']
+        """
+        return [
+            email
+            for email, recipient in self.recipients.items()
+            if recipient.status in {'failed', 'rejected', 'invalid'}
+        ]
+
+    def get_successful_recipients(self) -> list[str]:
+        """
+        Get list of email addresses that were successfully sent or queued.
+
+        Returns:
+            List of email addresses with sent/queued status.
+
+        Example:
+            >>> status = SendStatus(recipients={
+            ...     'good@example.com': RecipientStatus(status='sent'),
+            ...     'bad@example.com': RecipientStatus(status='failed'),
+            ... })
+            >>> status.get_successful_recipients()
+            ['good@example.com']
+        """
+        return [
+            email for email, recipient in self.recipients.items() if recipient.status in {'sent', 'queued'}
+        ]

amsdal_mail/webhooks/base.py

@@ -0,0 +1,32 @@
+"""Abstract base class for webhook parsers."""
+
+from abc import ABC
+from abc import abstractmethod
+
+from amsdal_mail.events import EmailTrackingContext
+
+
+class BaseWebhookParser(ABC):
+    @abstractmethod
+    def verify(self, body: bytes, headers: dict[str, str]) -> bool:
+        """Verify webhook request authenticity.
+
+        Args:
+            body: Raw request body bytes.
+            headers: HTTP request headers.
+
+        Returns:
+            True if the request is valid.
+        """
+
+    @abstractmethod
+    def parse(self, body: bytes, headers: dict[str, str]) -> list[EmailTrackingContext]:
+        """Parse webhook payload into tracking events.
+
+        Args:
+            body: Raw request body bytes.
+            headers: HTTP request headers.
+
+        Returns:
+            List of normalized tracking contexts.
+        """

amsdal_mail/webhooks/handler.py

@@ -0,0 +1,43 @@
+"""Webhook HTTP handler for receiving ESP tracking events."""
+
+from enum import StrEnum
+from typing import Any
+
+from amsdal_utils.events import EventBus
+
+from amsdal_mail.events import EmailTrackingEvent
+from amsdal_mail.webhooks.registry import WebhookRegistry
+
+
+class SupportedESP(StrEnum):
+    ses = 'ses'
+
+
+async def webhook_handler(esp_name: SupportedESP, request: Any) -> dict[str, Any]:
+    """Handle incoming webhook POST from ESP.
+
+    Args:
+        esp_name: Which ESP is sending the webhook (path parameter).
+        request: FastAPI Request object.
+
+    Returns:
+        JSON response with status and count of processed events.
+    """
+    from fastapi import HTTPException  # type: ignore[import-not-found]
+
+    parser = WebhookRegistry.get_parser(esp_name.value)
+    if not parser:
+        raise HTTPException(status_code=404, detail=f'No parser registered for ESP: {esp_name.value}')
+
+    body = await request.body()
+    headers = dict(request.headers)
+
+    if not parser.verify(body, headers):
+        raise HTTPException(status_code=403, detail='Webhook verification failed')
+
+    events = parser.parse(body, headers)
+
+    for event in events:
+        await EventBus.aemit(EmailTrackingEvent, event)
+
+    return {'status': 'ok', 'events_processed': len(events)}

amsdal_mail/webhooks/listener.py

@@ -0,0 +1,41 @@
+"""Route registration listener for webhook endpoints."""
+
+from amsdal_server.apps.common.events.server import RouterSetupContext  # type: ignore[import-not-found]
+from amsdal_utils.events import AsyncNextFn
+from amsdal_utils.events import EventListener
+from amsdal_utils.events import NextFn
+from fastapi import APIRouter  # type: ignore[import-not-found]
+from fastapi import Request
+
+from amsdal_mail.webhooks.handler import SupportedESP
+from amsdal_mail.webhooks.handler import webhook_handler
+
+
+class WebhookRouterListener(EventListener[RouterSetupContext]):
+    """Subscribes to RouterSetupEvent and registers the webhook route."""
+
+    def handle(
+        self,
+        context: RouterSetupContext,
+        next_fn: NextFn[RouterSetupContext],
+    ) -> RouterSetupContext:
+        from amsdal_mail.settings import mail_settings
+
+        base_path = mail_settings.WEBHOOK_BASE_PATH
+
+        router = APIRouter()
+
+        @router.post(f'{base_path}/{{esp_name}}', include_in_schema=False)
+        async def _webhook(esp_name: SupportedESP, request: Request) -> dict[str, object]:
+            return await webhook_handler(esp_name, request)
+
+        context.app.include_router(router)
+
+        return next_fn(context)
+
+    async def ahandle(
+        self,
+        context: RouterSetupContext,
+        next_fn: AsyncNextFn[RouterSetupContext],
+    ) -> RouterSetupContext:
+        return self.handle(context, next_fn)  # type: ignore[arg-type,unused-ignore]

amsdal_mail/webhooks/registry.py

@@ -0,0 +1,21 @@
+"""Webhook parser registry."""
+
+from typing import ClassVar
+
+from amsdal_mail.webhooks.base import BaseWebhookParser
+
+
+class WebhookRegistry:
+    _parsers: ClassVar[dict[str, BaseWebhookParser]] = {}
+
+    @classmethod
+    def register(cls, esp_name: str, parser: BaseWebhookParser) -> None:
+        cls._parsers[esp_name] = parser
+
+    @classmethod
+    def get_parser(cls, esp_name: str) -> BaseWebhookParser | None:
+        return cls._parsers.get(esp_name)
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._parsers.clear()

amsdal_mail/webhooks/ses.py

@@ -0,0 +1,201 @@
+"""AWS SES webhook parser via SNS notifications."""
+
+import json
+import logging
+from datetime import datetime
+from typing import Any
+
+from amsdal_mail.events import EmailTrackingContext
+from amsdal_mail.events import TrackingEventType
+from amsdal_mail.webhooks.base import BaseWebhookParser
+
+logger = logging.getLogger(__name__)
+
+_SES_EVENT_MAP: dict[str, TrackingEventType] = {
+    'Send': TrackingEventType.SENT,
+    'Delivery': TrackingEventType.DELIVERED,
+    'Bounce': TrackingEventType.BOUNCED,
+    'Complaint': TrackingEventType.COMPLAINED,
+    'Reject': TrackingEventType.REJECTED,
+    'Open': TrackingEventType.OPENED,
+    'Click': TrackingEventType.CLICKED,
+    'DeliveryDelay': TrackingEventType.DEFERRED,
+}
+
+
+class SESWebhookParser(BaseWebhookParser):
+    """Parse SES event notifications delivered via SNS.
+
+    SES sends events to an SNS topic, which then delivers them
+    as HTTP POST requests to the webhook endpoint. The payload
+    is an SNS message envelope containing the SES event JSON.
+
+    Args:
+        secret: Optional secret for HTTP basic auth verification.
+    """
+
+    def __init__(self, secret: str | None = None) -> None:
+        self.secret = secret
+
+    def verify(self, body: bytes, headers: dict[str, str]) -> bool:
+        """Verify SNS message by cross-validating headers against body.
+
+        Checks that SNS headers (x-amz-sns-message-type, x-amz-sns-message-id)
+        match the corresponding fields in the JSON body (Type, MessageId).
+        This prevents trivial forgery where only headers are spoofed.
+
+        TODO: add signature verification https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message.html
+        """
+        header_type = headers.get('x-amz-sns-message-type')
+        header_id = headers.get('x-amz-sns-message-id')
+
+        if not header_type or not header_id:
+            return False
+
+        if header_type not in ('SubscriptionConfirmation', 'Notification', 'UnsubscribeConfirmation'):
+            return False
+
+        try:
+            sns_message = json.loads(body)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return False
+
+        body_type = sns_message.get('Type')
+        body_id = sns_message.get('MessageId')
+
+        if header_type != body_type or header_id != body_id:
+            return False
+
+        return True
+
+    def parse(self, body: bytes, headers: dict[str, str]) -> list[EmailTrackingContext]:
+        """Parse SNS notification containing SES event.
+
+        Handles both SubscriptionConfirmation (returns empty list)
+        and Notification messages (returns tracking events).
+        """
+        message_type = headers.get('x-amz-sns-message-type', '')
+
+        sns_message = json.loads(body)
+
+        if message_type == 'SubscriptionConfirmation':
+            logger.info('SNS subscription confirmation received. SubscribeURL: %s', sns_message.get('SubscribeURL'))
+            return []
+
+        if message_type == 'UnsubscribeConfirmation':
+            logger.info('SNS unsubscribe confirmation received.')
+            return []
+
+        # Notification - parse the SES event from the Message field
+        ses_event = json.loads(sns_message.get('Message', '{}'))
+
+        return self._parse_ses_event(ses_event)
+
+    def _parse_ses_event(self, ses_event: dict[str, Any]) -> list[EmailTrackingContext]:
+        """Parse SES event JSON into tracking contexts.
+
+        Expands multi-recipient events (e.g. a bounce with 3 recipients)
+        into individual EmailTrackingContext instances.
+        """
+        event_type_str = ses_event.get('eventType', '')
+        tracking_type = _SES_EVENT_MAP.get(event_type_str, TrackingEventType.UNKNOWN)
+
+        mail_obj = ses_event.get('mail', {})
+        message_id = mail_obj.get('messageId', '')
+        tags = self._extract_tags(mail_obj)
+        metadata = self._extract_metadata(mail_obj)
+
+        detail_key = self._get_detail_key(event_type_str)
+        detail = ses_event.get(detail_key, {}) if detail_key else {}
+
+        timestamp = self._parse_timestamp(detail, ses_event)
+        recipients = self._extract_recipients(event_type_str, detail, mail_obj)
+        reject_reason = self._extract_reject_reason(event_type_str, detail)
+        description = self._extract_description(event_type_str, detail)
+        click_url = detail.get('link') if event_type_str == 'Click' else None
+        user_agent = detail.get('userAgent') if event_type_str in ('Open', 'Click') else None
+
+        contexts = []
+        for recipient in recipients:
+            contexts.append(
+                EmailTrackingContext(
+                    event_type=tracking_type,
+                    message_id=message_id,
+                    recipient=recipient,
+                    timestamp=timestamp,
+                    esp_name='ses',
+                    tags=tags,
+                    metadata=metadata,
+                    reject_reason=reject_reason,
+                    description=description,
+                    click_url=click_url,
+                    user_agent=user_agent,
+                    raw_event=ses_event,
+                )
+            )
+
+        return contexts
+
+    def _get_detail_key(self, event_type: str) -> str | None:
+        key_map = {
+            'Bounce': 'bounce',
+            'Complaint': 'complaint',
+            'Delivery': 'delivery',
+            'Send': 'send',
+            'Reject': 'reject',
+            'Open': 'open',
+            'Click': 'click',
+            'DeliveryDelay': 'deliveryDelay',
+        }
+        return key_map.get(event_type)
+
+    def _parse_timestamp(self, detail: dict[str, Any], ses_event: dict[str, Any]) -> datetime:
+        ts_str = detail.get('timestamp') or ses_event.get('mail', {}).get('timestamp', '')
+        if ts_str:
+            return datetime.fromisoformat(ts_str.replace('Z', '+00:00'))
+        return datetime.now()  # noqa: DTZ005
+
+    def _extract_recipients(
+        self, event_type: str, detail: dict[str, Any], mail_obj: dict[str, Any]
+    ) -> list[str]:
+        if event_type == 'Bounce':
+            return [r.get('emailAddress', '') for r in detail.get('bouncedRecipients', [])]
+        if event_type == 'Complaint':
+            return [r.get('emailAddress', '') for r in detail.get('complainedRecipients', [])]
+        if event_type == 'Delivery':
+            return detail.get('recipients', [])
+        # For Send, Reject, Open, Click, DeliveryDelay - use mail destination
+        return mail_obj.get('destination', [])
+
+    def _extract_tags(self, mail_obj: dict[str, Any]) -> list[str]:
+        tags_dict = mail_obj.get('tags', {})
+        result = []
+        for key, values in tags_dict.items():
+            for val in values:
+                result.append(f'{key}:{val}')
+        return result
+
+    def _extract_metadata(self, mail_obj: dict[str, Any]) -> dict[str, Any]:
+        headers = mail_obj.get('headers', [])
+        metadata: dict[str, Any] = {}
+        for header in headers:
+            name = header.get('name', '')
+            if name.startswith('X-Metadata-'):
+                metadata[name.removeprefix('X-Metadata-')] = header.get('value', '')
+        return metadata
+
+    def _extract_reject_reason(self, event_type: str, detail: dict[str, Any]) -> str | None:
+        if event_type == 'Bounce':
+            return detail.get('bounceSubType') or detail.get('bounceType')
+        if event_type == 'Reject':
+            return detail.get('reason')
+        return None
+
+    def _extract_description(self, event_type: str, detail: dict[str, Any]) -> str | None:
+        if event_type == 'Bounce':
+            recipients = detail.get('bouncedRecipients', [])
+            if recipients:
+                return recipients[0].get('diagnosticCode')
+        if event_type == 'DeliveryDelay':
+            return detail.get('delayType')
+        return None