Feat/email log model

backend/src/apps/owasp/admin/__init__.py

@@ -7,6 +7,7 @@
 from .board_of_directors import BoardOfDirectorsAdmin
 from .chapter import ChapterAdmin
 from .committee import CommitteeAdmin
+from .email_log import EmailLogAdmin
 from .entity_channel import EntityChannelAdmin
 from .entity_member import EntityMemberAdmin
 from .event import EventAdmin

backend/src/apps/owasp/admin/email_log.py

@@ -0,0 +1,32 @@
+"""Admin registration for EmailLog model."""
+
+from django.contrib import admin
+
+from apps.owasp.models.email_log import EmailLog
+
+
+class EmailLogAdmin(admin.ModelAdmin):
+    """Admin for EmailLog model."""
+
+    list_display = ("get_user", "snapshot", "status", "created_at")
+    list_filter = ("status", "created_at")
+    search_fields = ("snapshot_subscription__user__email",)
+    readonly_fields = (
+        "snapshot_subscription",
+        "snapshot",
+        "status",
+        "error_message",
+        "created_at",
+    )
+
+    def has_add_permission(self, request):
+        """Prevent manual creation of email logs."""
+        return False
+
+    @admin.display(description="User")
+    def get_user(self, obj):
+        """Return the user from the subscription."""
+        return obj.snapshot_subscription.user if obj.snapshot_subscription else "—"
+
+
+admin.site.register(EmailLog, EmailLogAdmin)

backend/src/apps/owasp/migrations/0076_emaillog.py

@@ -0,0 +1,65 @@
+# Generated by Django 5.2 on 2026-08-13 18:42
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("owasp", "0075_snapshotsubscription"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="EmailLog",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[("sent", "Sent"), ("failed", "Failed")], max_length=10
+                    ),
+                ),
+                ("error_message", models.TextField(blank=True, default="")),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "snapshot",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="email_logs",
+                        to="owasp.snapshot",
+                    ),
+                ),
+                (
+                    "snapshot_subscription",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="email_logs",
+                        to="owasp.snapshotsubscription",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name_plural": "Email Logs",
+                "db_table": "owasp_email_logs",
+                "indexes": [
+                    models.Index(fields=["-created_at"], name="owasp_email_log_created_idx")
+                ],
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=["snapshot_subscription", "snapshot"],
+                        condition=models.Q(status="sent"),
+                        name="unique_email_per_subscription_snapshot",
+                    )
+                ],
+            },
+        ),
+    ]

backend/src/apps/owasp/models/__init__.py

@@ -1,6 +1,7 @@
 from .board_of_directors import BoardOfDirectors
 from .chapter import Chapter
 from .committee import Committee
+from .email_log import EmailLog
 from .entity_channel import EntityChannel
 from .entity_member import EntityMember
 from .event import Event

backend/src/apps/owasp/models/email_log.py

@@ -0,0 +1,113 @@
+"""OWASP app email log model."""
+
+from django.db import models
+
+from apps.owasp.models.snapshot import Snapshot
+from apps.owasp.models.snapshot_subscription import SnapshotSubscription
+
+
+class EmailLog(models.Model):
+    """Model for tracking sent digest emails and preventing duplicates.
+
+    Each log entry links a SnapshotSubscription to the Snapshot it was sent for.
+    The unique constraint ensures no duplicate emails per subscription per snapshot.
+    """
+
+    class Meta:
+        """Model options."""
+
+        db_table = "owasp_email_logs"
+        verbose_name_plural = "Email Logs"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["snapshot_subscription", "snapshot"],
+                condition=models.Q(status="sent"),
+                name="unique_email_per_subscription_snapshot",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["-created_at"], name="owasp_email_log_created_idx"),
+        ]
+
+    class Status(models.TextChoices):
+        """Email delivery status choices."""
+
+        SENT = "sent", "Sent"
+        FAILED = "failed", "Failed"
+
+    snapshot_subscription = models.ForeignKey(
+        SnapshotSubscription,
+        on_delete=models.CASCADE,
+        related_name="email_logs",
+    )
+    snapshot = models.ForeignKey(
+        Snapshot,
+        on_delete=models.CASCADE,
+        related_name="email_logs",
+    )
+    status = models.CharField(
+        max_length=10,
+        choices=Status.choices,
+    )
+    error_message = models.TextField(blank=True, default="")
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        """Return a string representation."""
+        return f"{self.snapshot_subscription.user} — {self.snapshot.key} ({self.status})"
+
+    @classmethod
+    def is_duplicate(cls, *, snapshot, snapshot_subscription):
+        """Check if a digest email has already been sent.
+
+        Args:
+            snapshot: The snapshot instance.
+            snapshot_subscription: The snapshot subscription instance.
+
+        Returns:
+            True if a log entry already exists for this combination.
+
+        """
+        return cls.objects.filter(
+            snapshot=snapshot,
+            snapshot_subscription=snapshot_subscription,
+            status=cls.Status.SENT,
+        ).exists()
+
+    @classmethod
+    def mark_sent(cls, *, snapshot, snapshot_subscription):
+        """Record a successfully sent email.
+
+        Args:
+            snapshot: The snapshot instance.
+            snapshot_subscription: The snapshot subscription instance.
+
+        Returns:
+            The created EmailLog instance.
+
+        """
+        return cls.objects.create(
+            snapshot=snapshot,
+            snapshot_subscription=snapshot_subscription,
+            status=cls.Status.SENT,
+        )
+
+    @classmethod
+    def mark_failed(cls, *, snapshot, snapshot_subscription, error_message=""):
+        """Record a failed email delivery attempt.
+
+        Args:
+            snapshot: The snapshot instance.
+            snapshot_subscription: The snapshot subscription instance.
+            error_message: Description of the failure.
+
+        Returns:
+            The created EmailLog instance.
+
+        """
+        return cls.objects.create(
+            snapshot=snapshot,
+            snapshot_subscription=snapshot_subscription,
+            status=cls.Status.FAILED,
+            error_message=error_message,
+        )

backend/src/apps/owasp/services/email/base.py

@@ -0,0 +1,47 @@
+"""Abstract base class for email service providers."""
+
+from abc import ABC, abstractmethod
+
+
+class EmailService(ABC):
+    """Abstract email service provider.
+
+    Provides an abstraction layer that makes it easy to switch between
+    email sending service providers (e.g., Django SMTP, AWS SES, Resend).
+    """
+
+    @abstractmethod
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html_body: str,
+        plain_body: str,
+        headers: dict[str, str] | None = None,
+    ) -> bool:
+        """Send a single email.
+
+        Args:
+            to: Recipient email address.
+            subject: Email subject line.
+            html_body: HTML version of the email body.
+            plain_body: Plain text version of the email body.
+            headers: Optional custom email headers.
+
+        Returns:
+            True if the email was sent successfully.
+
+        """
+
+    @abstractmethod
+    def send_bulk(self, messages: list[dict]) -> dict:
+        """Send multiple emails.
+
+        Args:
+            messages: List of dicts, each containing 'to', 'subject',
+                     'html_body', and 'plain_body' keys.
+
+        Returns:
+            Dict with 'sent' and 'failed' counts.
+
+        """

backend/src/apps/owasp/services/email/django_email.py

@@ -0,0 +1,91 @@
+"""Django email service implementation."""
+
+import logging
+
+from django.conf import settings
+from django.core.mail import EmailMultiAlternatives, get_connection
+
+from apps.owasp.services.email.base import EmailService
+
+logger = logging.getLogger(__name__)
+
+
+class DjangoEmailService(EmailService):
+    """Email service using Django's EMAIL_BACKEND.
+
+    Works with any Django email backend including:
+    - Console (local dev)
+    - SMTP
+    - AWS SES (via django-ses)
+    """
+
+    def send(
+        self,
+        to: str,
+        subject: str,
+        html_body: str,
+        plain_body: str,
+        headers: dict[str, str] | None = None,
+    ) -> bool:
+        """Send a single email using Django's EmailMultiAlternatives."""
+        try:
+            msg = EmailMultiAlternatives(
+                subject=subject,
+                body=plain_body,
+                from_email=settings.DEFAULT_FROM_EMAIL,
+                to=[to],
+                headers=headers,
+            )
+            msg.attach_alternative(html_body, "text/html")
+            sent_count = msg.send()
+        except Exception:
+            logger.exception("Failed to send email")
+            raise
+        return sent_count > 0
+
+    def _close_connection_safely(self, connection) -> None:
+        """Safely close the email connection, logging any exceptions."""
+        if connection:
+            try:
+                connection.close()
+            except Exception:
+                logger.exception("Failed to close email connection")
+
+    def send_bulk(self, messages: list[dict]) -> dict:
+        """Send multiple emails using a single shared connection."""
+        results = {"sent": 0, "failed": 0}
+        if not messages:
+            return results
+
+        connection = None
+        try:
+            connection = get_connection()
+            connection.open()
+        except Exception:
+            logger.exception("Failed to open email connection")
+            self._close_connection_safely(connection)
+            return {"sent": 0, "failed": len(messages)}
+
+        try:
+            for message in messages:
+                try:
+                    msg = EmailMultiAlternatives(
+                        subject=message["subject"],
+                        body=message["plain_body"],
+                        from_email=settings.DEFAULT_FROM_EMAIL,
+                        to=[message["to"]],
+                        headers=message.get("headers"),
+                        connection=connection,
+                    )
+                    msg.attach_alternative(message["html_body"], "text/html")
+                    if msg.send() > 0:
+                        results["sent"] += 1
+                    else:
+                        results["failed"] += 1
+                except Exception:
+                    logger.exception("Failed to send email")
+                    results["failed"] += 1
+        finally:
+            self._close_connection_safely(connection)
+
+        return results

backend/src/apps/owasp/services/email/factory.py

@@ -0,0 +1,16 @@
+"""Email service factory."""
+
+from apps.owasp.services.email.base import EmailService
+from apps.owasp.services.email.django_email import DjangoEmailService
+
+
+def get_email_service() -> EmailService:
+    """Return the configured email service.
+
+    Currently returns DjangoEmailService, which works with any
+    Django EMAIL_BACKEND (console, SMTP, AWS SES).
+
+    To add a new provider, create a new EmailService subclass
+    and add a settings-based switch here.
+    """
+    return DjangoEmailService()

backend/src/settings/base.py

@@ -41,6 +41,8 @@ class Base(Configuration):
     SITE_NAME = "localhost"
     SITE_URL = "http://localhost:8000"
 
+    DEFAULT_FROM_EMAIL = "OWASP Nest <noreply@owasp.org>"
+
     DJANGO_APPS = (
         "django.contrib.admin",
         "django.contrib.auth",