amsdal_mail 0.1.0__py3-none-any.whl

amsdal_mail/backends/smtp.py

@@ -0,0 +1,305 @@
+"""SMTP email backend."""
+
+import os
+import smtplib
+import ssl
+from typing import Any
+
+try:
+    import aiosmtplib
+except ImportError:
+    aiosmtplib = None  # type: ignore[assignment]
+
+from amsdal_mail.backends.base import BaseEmailBackend
+from amsdal_mail.exceptions import EmailConnectionError
+from amsdal_mail.exceptions import SendError
+from amsdal_mail.message import EmailMessage
+from amsdal_mail.status import RecipientStatus
+from amsdal_mail.status import SendStatus
+
+_SMTP_PERMANENT_ERROR_CODE = 500
+
+
+class SMTPBackend(BaseEmailBackend):
+    """
+    Email backend that sends messages via SMTP.
+
+    Supports TLS/SSL encryption and authentication.
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str | None = None,
+        port: int | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        use_tls: bool | None = None,
+        use_ssl: bool | None = None,
+        timeout: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the SMTP backend.
+
+        Args:
+            host: SMTP server hostname (env: AMSDAL_EMAIL_HOST)
+            port: SMTP server port (env: AMSDAL_EMAIL_PORT)
+            username: Authentication username (env: AMSDAL_EMAIL_USER)
+            password: Authentication password (env: AMSDAL_EMAIL_PASSWORD)
+            use_tls: Use STARTTLS (env: AMSDAL_EMAIL_USE_TLS)
+            use_ssl: Use SSL/TLS from start (env: AMSDAL_EMAIL_USE_SSL)
+            timeout: Connection timeout in seconds (env: AMSDAL_EMAIL_TIMEOUT)
+            **kwargs: Additional backend options
+        """
+        super().__init__(**kwargs)
+
+        # Load configuration from environment if not provided
+        self.host = host or os.environ.get('AMSDAL_EMAIL_HOST', 'localhost')
+        self.port = port or int(os.environ.get('AMSDAL_EMAIL_PORT', '25'))
+        self.username = username or os.environ.get('AMSDAL_EMAIL_USER')
+        self.password = password or os.environ.get('AMSDAL_EMAIL_PASSWORD')
+        self.use_tls = use_tls if use_tls is not None else os.environ.get('AMSDAL_EMAIL_USE_TLS', '').lower() == 'true'
+        self.use_ssl = use_ssl if use_ssl is not None else os.environ.get('AMSDAL_EMAIL_USE_SSL', '').lower() == 'true'
+        self.timeout = timeout or int(os.environ.get('AMSDAL_EMAIL_TIMEOUT', '30'))
+
+        self.connection: smtplib.SMTP | smtplib.SMTP_SSL | None = None
+
+    def open(self) -> None:
+        """
+        Open a connection to the SMTP server.
+
+        Raises:
+            EmailConnectionError: If connection fails and fail_silently is False
+        """
+        if self.connection:
+            return
+
+        try:
+            if self.use_ssl:
+                # Create SSL context
+                context = ssl.create_default_context()
+                self.connection = smtplib.SMTP_SSL(
+                    self.host,
+                    self.port,
+                    timeout=self.timeout,
+                    context=context,
+                )
+            else:
+                self.connection = smtplib.SMTP(
+                    self.host,
+                    self.port,
+                    timeout=self.timeout,
+                )
+
+                if self.use_tls:
+                    # Upgrade connection to TLS
+                    context = ssl.create_default_context()
+                    self.connection.starttls(context=context)
+
+            # Authenticate if credentials provided
+            if self.username and self.password:
+                self.connection.login(self.username, self.password)
+
+        except (smtplib.SMTPException, OSError, TimeoutError) as e:
+            if not self.fail_silently:
+                msg = f'Failed to connect to SMTP server: {e}'
+                raise EmailConnectionError(msg) from e
+
+    def close(self) -> None:
+        """Close the connection to the SMTP server."""
+        if self.connection:
+            try:
+                self.connection.quit()
+            except (smtplib.SMTPException, OSError):
+                # If quit() fails, try close() instead
+                try:
+                    self.connection.close()
+                except (smtplib.SMTPException, OSError):
+                    pass
+            finally:
+                self.connection = None
+
+    def send_messages(self, email_messages: list[EmailMessage]) -> SendStatus:
+        """
+        Send one or more email messages via SMTP.
+
+        Args:
+            email_messages: List of EmailMessage instances to send
+
+        Returns:
+            SendStatus with per-recipient information
+
+        Raises:
+            SendError: If sending fails and fail_silently is False
+        """
+        status = SendStatus()
+
+        if not email_messages:
+            return status
+
+        # Open connection
+        self.open()
+
+        if not self.connection:
+            return status
+
+        new_connection = True
+        recipients = {}
+
+        try:
+            for message in email_messages:
+                try:
+                    # Convert to MIME format
+                    mime_message = message.as_mime()
+
+                    # Send message - returns dict of refused recipients
+                    refused = self.connection.sendmail(
+                        str(message.from_email),
+                        message.recipients(),
+                        mime_message.as_string(),
+                    )
+
+                    # Process results for each recipient
+                    for recipient in message.recipients():
+                        if recipient in refused:
+                            # Recipient was refused
+                            smtp_code, _smtp_msg = refused[recipient]
+                            recipients[recipient] = RecipientStatus(
+                                message_id=None,
+                                status='rejected' if smtp_code >= _SMTP_PERMANENT_ERROR_CODE else 'failed',
+                            )
+                        else:
+                            # Recipient was accepted
+                            recipients[recipient] = RecipientStatus(
+                                message_id=None,  # SMTP doesn't provide message IDs
+                                status='sent',
+                            )
+
+                except (smtplib.SMTPException, OSError) as e:
+                    # All recipients failed for this message
+                    for recipient in message.recipients():
+                        recipients[recipient] = RecipientStatus(
+                            message_id=None,
+                            status='failed',
+                        )
+
+                    if not self.fail_silently:
+                        msg = f'Failed to send email: {e}'
+                        raise SendError(msg) from e
+
+        finally:
+            # Close connection if we opened it
+            if new_connection:
+                self.close()
+
+        status.set_recipient_status(recipients)
+        return status
+
+    async def asend_messages(self, email_messages: list[EmailMessage]) -> SendStatus:
+        """
+        Send one or more email messages via SMTP asynchronously.
+
+        Args:
+            email_messages: List of EmailMessage instances to send
+
+        Returns:
+            SendStatus with per-recipient information
+
+        Raises:
+            SendError: If sending fails and fail_silently is False
+            ImportError: If aiosmtplib is not installed
+        """
+        if aiosmtplib is None:
+            msg = 'aiosmtplib is required for async SMTP. Install with: pip install amsdal-mail[smtp]'
+            raise ImportError(msg)
+
+        status = SendStatus()
+
+        if not email_messages:
+            return status
+
+        recipients = {}
+
+        try:
+            # Create async SMTP client
+            if self.use_ssl:
+                smtp = aiosmtplib.SMTP(
+                    hostname=self.host,
+                    port=self.port,
+                    timeout=self.timeout,
+                    use_tls=True,
+                )
+            else:
+                smtp = aiosmtplib.SMTP(
+                    hostname=self.host,
+                    port=self.port,
+                    timeout=self.timeout,
+                    use_tls=False,
+                    start_tls=self.use_tls,
+                )
+
+            # Connect and authenticate
+            await smtp.connect()
+
+            if self.use_tls and not self.use_ssl:
+                await smtp.starttls(validate_certs=True)
+
+            if self.username and self.password:
+                await smtp.login(self.username, self.password)
+
+            # Send messages
+            for message in email_messages:
+                try:
+                    # Convert to MIME format
+                    mime_message = message.as_mime()
+
+                    # Send message - aiosmtplib returns (response, message) tuple or errors dict
+                    result = await smtp.sendmail(
+                        str(message.from_email),
+                        message.recipients(),
+                        mime_message.as_string(),
+                    )
+
+                    # aiosmtplib sendmail returns errors dict (like smtplib)
+                    # Empty dict means all recipients accepted
+                    refused: dict[str, Any] = result if isinstance(result, dict) else {}
+
+                    # Process results for each recipient
+                    for recipient in message.recipients():
+                        if recipient in refused:
+                            # Recipient was refused
+                            smtp_code, _smtp_msg = refused[recipient]
+                            recipients[recipient] = RecipientStatus(
+                                message_id=None,
+                                status='rejected' if smtp_code >= _SMTP_PERMANENT_ERROR_CODE else 'failed',
+                            )
+                        else:
+                            # Recipient was accepted
+                            recipients[recipient] = RecipientStatus(
+                                message_id=None,  # SMTP doesn't provide message IDs
+                                status='sent',
+                            )
+
+                except (aiosmtplib.SMTPException, OSError) as e:
+                    # All recipients failed for this message
+                    for recipient in message.recipients():
+                        recipients[recipient] = RecipientStatus(
+                            message_id=None,
+                            status='failed',
+                        )
+
+                    if not self.fail_silently:
+                        msg = f'Failed to send email: {e}'
+                        raise SendError(msg) from e
+
+            # Close connection
+            await smtp.quit()
+
+        except (aiosmtplib.SMTPException, OSError, TimeoutError) as e:
+            if not self.fail_silently:
+                msg = f'Failed to connect to SMTP server: {e}'
+                raise EmailConnectionError(msg) from e
+
+        status.set_recipient_status(recipients)
+        return status

amsdal_mail/events.py

@@ -0,0 +1,46 @@
+"""Webhook tracking event definitions."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from amsdal_utils.events import ErrorStrategy
+from amsdal_utils.events import Event
+from amsdal_utils.events import EventContext
+from pydantic import Field
+
+
+class TrackingEventType(StrEnum):
+    QUEUED = 'queued'
+    SENT = 'sent'
+    DELIVERED = 'delivered'
+    DEFERRED = 'deferred'
+    BOUNCED = 'bounced'
+    REJECTED = 'rejected'
+    FAILED = 'failed'
+    OPENED = 'opened'
+    CLICKED = 'clicked'
+    COMPLAINED = 'complained'
+    UNSUBSCRIBED = 'unsubscribed'
+    UNKNOWN = 'unknown'
+
+
+class EmailTrackingContext(EventContext):
+    event_type: TrackingEventType
+    message_id: str
+    recipient: str
+    timestamp: datetime
+    esp_name: str
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    reject_reason: str | None = None
+    description: str | None = None
+    click_url: str | None = None
+    user_agent: str | None = None
+    raw_event: dict[str, Any] = Field(default_factory=dict)
+
+
+class EmailTrackingEvent(Event[EmailTrackingContext]):
+    """Emitted when webhook receives tracking event from ESP."""
+
+    default_error_strategy = ErrorStrategy.LOG_AND_CONTINUE

amsdal_mail/exceptions.py

@@ -0,0 +1,25 @@
+"""Exception classes for amsdal_mail."""
+
+
+class EmailError(Exception):
+    """Base exception for all email-related errors."""
+
+    pass
+
+
+class ConfigurationError(EmailError):
+    """Raised when an email backend is misconfigured."""
+
+    pass
+
+
+class EmailConnectionError(EmailError):
+    """Raised when a connection to an email service fails."""
+
+    pass
+
+
+class SendError(EmailError):
+    """Raised when sending an email message fails."""
+
+    pass

amsdal_mail/message.py

@@ -0,0 +1,167 @@
+"""Email message data models."""
+
+from email.mime.base import MIMEBase
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import EmailStr
+from pydantic import Field
+from pydantic import field_validator
+from pydantic import model_validator
+
+
+class Attachment(BaseModel):
+    """Represents an email attachment."""
+
+    filename: str = Field(..., description='Attachment filename')
+    content: bytes = Field(..., description='File content as bytes')
+    mimetype: str = Field(..., description='MIME type (e.g., application/pdf)')
+    content_id: str | None = Field(default=None, description='Content-ID for inline images (used in cid: URLs)')
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class EmailMessage(BaseModel):
+    """Represents an email message."""
+
+    subject: str = Field(..., description='Email subject line')
+    body: str = Field(default='', description='Plain text body (optional if template_id is provided)')
+    from_email: EmailStr | str = Field(..., description='Sender email address')
+    to: list[EmailStr | str] = Field(..., description='Primary recipients')
+    cc: list[EmailStr | str] = Field(default_factory=list, description='Carbon copy recipients')
+    bcc: list[EmailStr | str] = Field(default_factory=list, description='Blind carbon copy recipients')
+    reply_to: list[EmailStr | str] = Field(default_factory=list, description='Reply-to addresses')
+    attachments: list[Attachment] = Field(default_factory=list, description='File attachments')
+    headers: dict[str, str] = Field(default_factory=dict, description='Custom email headers')
+    html_body: str | None = Field(default=None, description='HTML version of body')
+    tags: list[str] = Field(default_factory=list, description='Message tags for categorization and filtering')
+    metadata: dict[str, str] = Field(default_factory=dict, description='Custom key-value metadata for tracking')
+    template_id: str | None = Field(default=None, description='ESP template ID for templated emails')
+    merge_data: dict[str, dict[str, Any]] | None = Field(
+        default=None, description='Per-recipient template variables (recipient email -> variables)'
+    )
+    merge_global_data: dict[str, Any] | None = Field(
+        default=None, description='Global template variables for all recipients'
+    )
+    track_opens: bool = Field(
+        default=False, description='Enable open tracking (ESP inserts tracking pixel in HTML emails)'
+    )
+    track_clicks: bool = Field(default=False, description='Enable click tracking (ESP rewrites URLs to track clicks)')
+
+    model_config = ConfigDict(extra='allow')
+
+    @field_validator('to', 'cc', 'bcc', 'reply_to', mode='before')
+    @classmethod
+    def ensure_list(cls, v: Any) -> list[str]:
+        """Ensure email fields are lists."""
+        if isinstance(v, str):
+            return [v]
+        return v or []
+
+    @model_validator(mode='after')
+    def validate_body_or_template(self) -> 'EmailMessage':
+        """Ensure either body or template_id is provided."""
+        if not self.body and not self.template_id:
+            msg = 'Either body or template_id must be provided'
+            raise ValueError(msg)
+        return self
+
+    def as_mime(self) -> MIMEMultipart | MIMEText:
+        """Convert EmailMessage to MIME message for SMTP sending."""
+        from email import encoders
+
+        # Determine message structure
+        has_html = self.html_body is not None
+        inline_attachments = [a for a in self.attachments if a.content_id]
+        regular_attachments = [a for a in self.attachments if not a.content_id]
+        has_inline = len(inline_attachments) > 0
+        has_regular = len(regular_attachments) > 0
+
+        msg: MIMEMultipart | MIMEText
+
+        # Build the body part (text or alternative)
+        body_part: MIMEMultipart | MIMEText
+        if has_html:
+            body_part = MIMEMultipart('alternative')
+            body_part.attach(MIMEText(self.body, 'plain', 'utf-8'))
+            body_part.attach(MIMEText(self.html_body or '', 'html', 'utf-8'))
+        else:
+            body_part = MIMEText(self.body, 'plain', 'utf-8')
+
+        # Wrap with related if inline attachments exist
+        content_part: MIMEMultipart | MIMEText
+        if has_inline:
+            related_part = MIMEMultipart('related')
+            related_part.attach(body_part)
+            for attachment in inline_attachments:
+                part = MIMEBase(*attachment.mimetype.split('/', 1))
+                part.set_payload(attachment.content)
+                encoders.encode_base64(part)
+                part.add_header('Content-Disposition', 'inline', filename=attachment.filename)
+                part.add_header('Content-ID', f'<{attachment.content_id}>')
+                related_part.attach(part)
+            content_part = related_part
+        else:
+            content_part = body_part
+
+        # Wrap with mixed if regular attachments exist
+        if has_regular:
+            msg = MIMEMultipart('mixed')
+            msg.attach(content_part)
+            for attachment in regular_attachments:
+                part = MIMEBase(*attachment.mimetype.split('/', 1))
+                part.set_payload(attachment.content)
+                encoders.encode_base64(part)
+                part.add_header('Content-Disposition', f'attachment; filename="{attachment.filename}"')
+                msg.attach(part)
+        else:
+            msg = content_part
+
+        # Set headers
+        msg['Subject'] = self.subject
+        msg['From'] = self.from_email
+        msg['To'] = ', '.join(str(addr) for addr in self.to)
+
+        if self.cc:
+            msg['Cc'] = ', '.join(str(addr) for addr in self.cc)
+
+        if self.reply_to:
+            msg['Reply-To'] = ', '.join(str(addr) for addr in self.reply_to)
+
+        # Add custom headers
+        for key, value in self.headers.items():
+            msg[key] = value
+
+        return msg
+
+    def recipients(self) -> list[str]:
+        """Get all recipients (to, cc, bcc)."""
+        return [str(addr) for addr in self.to + self.cc + self.bcc]
+
+    def get_template_data(self, recipient: str) -> dict[str, Any]:
+        """
+        Get merged template data for a specific recipient.
+
+        Combines merge_global_data with recipient-specific merge_data.
+        Recipient-specific data takes precedence over global data.
+
+        Args:
+            recipient: Email address of the recipient
+
+        Returns:
+            Dictionary of template variables for the recipient
+        """
+        data: dict[str, Any] = {}
+
+        # Start with global data
+        if self.merge_global_data:
+            data.update(self.merge_global_data)
+
+        # Override with recipient-specific data
+        if self.merge_data and recipient in self.merge_data:
+            data.update(self.merge_data[recipient])
+
+        return data

amsdal_mail/settings.py

@@ -0,0 +1,21 @@
+"""Mail plugin settings."""
+
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+
+class MailSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix='AMSDAL_MAIL_',
+        case_sensitive=True,
+        env_file='.env',
+        env_file_encoding='utf-8',
+        extra='ignore',
+    )
+
+    WEBHOOK_ENABLED: bool = False
+    WEBHOOK_BASE_PATH: str = '/webhooks/mail'
+    WEBHOOK_SES_SECRET: str | None = None
+
+
+mail_settings = MailSettings()