sneakyklaus/docs/designs/v0.1.0/components/notifications.md

Notifications Component Design - v0.1.0

Version: 0.1.0 Date: 2025-12-22 Status: Initial Design

Introduction

This document defines the email notification system for Sneaky Klaus. The notification service handles all transactional and reminder emails sent to participants and administrators using Resend as the email delivery provider.

Requirements

Functional Requirements

1. Transactional Emails: Send immediate emails in response to user actions
2. Reminder Emails: Send scheduled reminder emails before exchange date
3. Admin Notifications: Notify admin of important exchange events (opt-in)
4. Magic Link Delivery: Include authentication tokens in emails
5. Template Management: Maintain consistent branded email templates
6. Error Handling: Gracefully handle email delivery failures

Non-Functional Requirements

1. Reliability: Guarantee delivery or retry on failure
2. Performance: Send emails asynchronously without blocking requests
3. Auditability: Log all email send attempts
4. Deliverability: Follow email best practices (SPF, DKIM, unsubscribe links)

Email Types

Participant Emails

Email Type	Trigger	Recipient	Time-Sensitive
Registration Confirmation	Participant registers	Participant	Yes (immediate)
Magic Link	Participant requests access	Participant	Yes (immediate)
Match Notification	Matching complete	All participants	Yes (immediate)
Reminder Email	Scheduled (pre-exchange)	Opted-in participants	Yes (scheduled)
Withdrawal Confirmation	Participant withdraws	Participant	Yes (immediate)

Admin Emails

Email Type	Trigger	Recipient	Time-Sensitive
Password Reset	Admin requests reset	Admin	Yes (immediate)
New Registration	Participant registers	Admin	No (opt-in)
Participant Withdrawal	Participant withdraws	Admin	No (opt-in)
Matching Complete	Matching succeeds	Admin	No (opt-in)
Data Purge Warning	7 days before purge	Admin	No

Notification Service Architecture

flowchart TB
    subgraph "Application Layer"
        Route[Route Handler]
        Service[Business Logic]
    end

    subgraph "Notification Service"
        NS[NotificationService]
        TemplateEngine[Template Renderer]
        EmailQueue[Email Queue]
    end

    subgraph "External Services"
        Resend[Resend API]
    end

    subgraph "Storage"
        DB[(Database)]
        Templates[Email Templates]
    end

    Route --> Service
    Service --> NS
    NS --> TemplateEngine
    TemplateEngine --> Templates
    NS --> EmailQueue
    EmailQueue --> Resend
    NS --> DB
    Resend --> DB

    style Resend fill:#f9f,stroke:#333
    style Templates fill:#bfb,stroke:#333

Implementation Structure

Service Class

class NotificationService:
    """
    Centralized service for all email notifications.
    """

    def __init__(self, resend_client: ResendClient = None):
        self.resend = resend_client or ResendClient(api_key=get_resend_api_key())
        self.template_renderer = EmailTemplateRenderer()
        self.logger = logging.getLogger(__name__)

    # Participant Emails
    def send_registration_confirmation(self, participant_id: int) -> EmailResult
    def send_magic_link(self, participant_id: int, token: str) -> EmailResult
    def send_match_notification(self, participant_id: int) -> EmailResult
    def send_reminder_email(self, participant_id: int) -> EmailResult
    def send_withdrawal_confirmation(self, participant_id: int) -> EmailResult

    # Admin Emails
    def send_password_reset(self, admin_email: str, token: str) -> EmailResult
    def send_admin_notification(self, exchange_id: int, notification_type: NotificationType) -> EmailResult
    def send_data_purge_warning(self, exchange_id: int) -> EmailResult

    # Batch Operations
    def send_match_notifications_batch(self, exchange_id: int) -> BatchEmailResult

    # Internal Methods
    def _send_email(self, email_request: EmailRequest) -> EmailResult
    def _log_email_send(self, email_request: EmailRequest, result: EmailResult)

Email Templates

Template Structure

All email templates use Jinja2 with HTML and plain text versions:

Directory Structure:

templates/emails/
├── base.html                    # Base template with header/footer
├── base.txt                     # Plain text base
├── participant/
│   ├── registration_confirmation.html
│   ├── registration_confirmation.txt
│   ├── magic_link.html
│   ├── magic_link.txt
│   ├── match_notification.html
│   ├── match_notification.txt
│   ├── reminder.html
│   ├── reminder.txt
│   └── withdrawal_confirmation.html
│   └── withdrawal_confirmation.txt
└── admin/
    ├── password_reset.html
    ├── password_reset.txt
    ├── new_registration.html
    ├── new_registration.txt
    ├── participant_withdrawal.html
    ├── participant_withdrawal.txt
    ├── matching_complete.html
    ├── matching_complete.txt
    ├── data_purge_warning.html
    └── data_purge_warning.txt

Base Template

base.html:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}Sneaky Klaus{% endblock %}</title>
    <style>
        /* Inline CSS for email client compatibility */
        body { font-family: Arial, sans-serif; line-height: 1.6; color: #333; }
        .container { max-width: 600px; margin: 0 auto; padding: 20px; }
        .header { background-color: #d32f2f; color: white; padding: 20px; text-align: center; }
        .content { padding: 30px; background-color: #f9f9f9; }
        .button { display: inline-block; padding: 12px 24px; background-color: #d32f2f; color: white; text-decoration: none; border-radius: 4px; }
        .footer { text-align: center; font-size: 12px; color: #666; padding: 20px; }
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1>🎅 Sneaky Klaus</h1>
        </div>
        <div class="content">
            {% block content %}{% endblock %}
        </div>
        <div class="footer">
            <p>You received this email because you're part of a Sneaky Klaus Secret Santa exchange.</p>
            {% block unsubscribe %}{% endblock %}
            <p>&copy; {{ current_year }} Sneaky Klaus</p>
        </div>
    </div>
</body>
</html>

base.txt:

SNEAKY KLAUS
=============

{% block content %}{% endblock %}

---
You received this email because you're part of a Sneaky Klaus Secret Santa exchange.
{% block unsubscribe %}{% endblock %}

© {{ current_year }} Sneaky Klaus

Participant Email Specifications

1. Registration Confirmation

Trigger: Immediately after participant registration

Subject: "Welcome to {exchange_name}!"

Template Variables:

{
    "participant_name": str,
    "exchange_name": str,
    "exchange_date": datetime,
    "budget": str,
    "magic_link_url": str,
    "app_url": str
}

Content (HTML version):

{% extends "emails/base.html" %}
{% block content %}
<h2>Welcome to {{ exchange_name }}!</h2>

<p>Hi {{ participant_name }},</p>

<p>You've successfully registered for the Secret Santa exchange!</p>

<p><strong>Exchange Details:</strong></p>
<ul>
    <li><strong>Event Date:</strong> {{ exchange_date|format_date }}</li>
    <li><strong>Gift Budget:</strong> {{ budget }}</li>
</ul>

<p>You can update your gift ideas or view participant information anytime using the link below:</p>

<p style="text-align: center;">
    <a href="{{ magic_link_url }}" class="button">Access My Registration</a>
</p>

<p><small>This link will expire in 1 hour. You can request a new one anytime from the registration page.</small></p>

<p>When participants are matched, you'll receive another email with your Secret Santa assignment.</p>

<p>Happy gifting!</p>
{% endblock %}

Plain Text Version: Similar content without HTML formatting

---

2. Magic Link

Trigger: Participant requests access to registration

Subject: "Access Your Sneaky Klaus Registration"

Template Variables:

{
    "participant_name": str,
    "exchange_name": str,
    "magic_link_url": str,
    "expiration_minutes": int  # 60
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Access Your Registration</h2>

<p>Hi {{ participant_name }},</p>

<p>You requested access to your registration for <strong>{{ exchange_name }}</strong>.</p>

<p style="text-align: center;">
    <a href="{{ magic_link_url }}" class="button">Access My Registration</a>
</p>

<p><small>This link will expire in {{ expiration_minutes }} minutes and can only be used once.</small></p>

<p>If you didn't request this link, you can safely ignore this email.</p>
{% endblock %}

---

3. Match Notification

Trigger: Matching complete (sent to all participants)

Subject: "Your Secret Santa Assignment for {exchange_name}"

Template Variables:

{
    "participant_name": str,
    "exchange_name": str,
    "exchange_date": datetime,
    "budget": str,
    "recipient_name": str,
    "recipient_gift_ideas": str,
    "magic_link_url": str,
    "participant_count": int
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Your Secret Santa Assignment</h2>

<p>Hi {{ participant_name }},</p>

<p>Participants have been matched for <strong>{{ exchange_name }}</strong>! 🎁</p>

<div style="background-color: white; padding: 20px; border-radius: 8px; border-left: 4px solid #d32f2f; margin: 20px 0;">
    <h3 style="margin-top: 0;">You're buying for:</h3>
    <p style="font-size: 18px; font-weight: bold; margin: 10px 0;">{{ recipient_name }}</p>

    {% if recipient_gift_ideas %}
    <p><strong>Gift Ideas:</strong></p>
    <p style="white-space: pre-wrap;">{{ recipient_gift_ideas }}</p>
    {% else %}
    <p><em>No gift ideas provided yet.</em></p>
    {% endif %}
</div>

<p><strong>Exchange Details:</strong></p>
<ul>
    <li><strong>Gift Budget:</strong> {{ budget }}</li>
    <li><strong>Exchange Date:</strong> {{ exchange_date|format_date }}</li>
    <li><strong>Total Participants:</strong> {{ participant_count }}</li>
</ul>

<p>You can view this information anytime by clicking the link below:</p>

<p style="text-align: center;">
    <a href="{{ magic_link_url }}" class="button">View My Assignment</a>
</p>

<p><strong>Remember:</strong> Keep your assignment secret! The fun is in the surprise. 🤫</p>

<p>Happy shopping!</p>
{% endblock %}

---

4. Reminder Email

Trigger: Scheduled (based on admin configuration, e.g., 7 days, 3 days, 1 day before exchange)

Subject: "Reminder: {exchange_name} is {days_until} days away!"

Template Variables:

{
    "participant_name": str,
    "exchange_name": str,
    "exchange_date": datetime,
    "days_until": int,
    "recipient_name": str,
    "recipient_gift_ideas": str,
    "budget": str,
    "magic_link_url": str
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Don't Forget! {{ exchange_name }} is Coming Up</h2>

<p>Hi {{ participant_name }},</p>

<p>This is a friendly reminder that <strong>{{ exchange_name }}</strong> is only <strong>{{ days_until }} day{{ 's' if days_until != 1 else '' }}</strong> away!</p>

<p>You're buying for: <strong>{{ recipient_name }}</strong></p>

{% if recipient_gift_ideas %}
<p><strong>Their Gift Ideas:</strong></p>
<p style="white-space: pre-wrap; background-color: white; padding: 15px; border-radius: 4px;">{{ recipient_gift_ideas }}</p>
{% endif %}

<p><strong>Gift Budget:</strong> {{ budget }}</p>
<p><strong>Exchange Date:</strong> {{ exchange_date|format_date }}</p>

<p style="text-align: center;">
    <a href="{{ magic_link_url }}" class="button">View Full Details</a>
</p>

<p>Happy shopping! 🎁</p>
{% endblock %}

{% block unsubscribe %}
<p><a href="{{ unsubscribe_url }}">Don't want reminders? Update your preferences</a></p>
{% endblock %}

---

5. Withdrawal Confirmation

Trigger: Participant withdraws from exchange

Subject: "You've withdrawn from {exchange_name}"

Template Variables:

{
    "participant_name": str,
    "exchange_name": str
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Withdrawal Confirmed</h2>

<p>Hi {{ participant_name }},</p>

<p>You've successfully withdrawn from <strong>{{ exchange_name }}</strong>.</p>

<p>You will no longer receive any emails about this exchange.</p>

<p>If this was a mistake, please contact the exchange organizer to re-register.</p>
{% endblock %}

Admin Email Specifications

1. Password Reset

Trigger: Admin requests password reset

Subject: "Password Reset Request - Sneaky Klaus"

Template Variables:

{
    "reset_link_url": str,
    "expiration_minutes": int  # 60
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Password Reset Request</h2>

<p>You requested a password reset for your Sneaky Klaus admin account.</p>

<p style="text-align: center;">
    <a href="{{ reset_link_url }}" class="button">Reset Password</a>
</p>

<p><small>This link will expire in {{ expiration_minutes }} minutes and can only be used once.</small></p>

<p>If you didn't request this reset, you can safely ignore this email. Your password will not be changed.</p>
{% endblock %}

---

2. New Registration (Admin Notification)

Trigger: Participant registers (if admin has enabled this notification)

Subject: "New Participant in {exchange_name}"

Template Variables:

{
    "exchange_name": str,
    "participant_name": str,
    "participant_email": str,
    "participant_count": int,
    "max_participants": int,
    "exchange_url": str
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>New Participant Registered</h2>

<p>A new participant has joined <strong>{{ exchange_name }}</strong>:</p>

<ul>
    <li><strong>Name:</strong> {{ participant_name }}</li>
    <li><strong>Email:</strong> {{ participant_email }}</li>
</ul>

<p><strong>Participant Count:</strong> {{ participant_count }} / {{ max_participants }}</p>

<p style="text-align: center;">
    <a href="{{ exchange_url }}" class="button">View Exchange</a>
</p>
{% endblock %}

---

3. Participant Withdrawal (Admin Notification)

Trigger: Participant withdraws (if admin has enabled this notification)

Subject: "Participant Withdrew from {exchange_name}"

Template Variables:

{
    "exchange_name": str,
    "participant_name": str,
    "participant_count": int,
    "exchange_url": str
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Participant Withdrew</h2>

<p><strong>{{ participant_name }}</strong> has withdrawn from <strong>{{ exchange_name }}</strong>.</p>

<p><strong>Remaining Participants:</strong> {{ participant_count }}</p>

<p style="text-align: center;">
    <a href="{{ exchange_url }}" class="button">View Exchange</a>
</p>
{% endblock %}

---

4. Matching Complete (Admin Notification)

Trigger: Matching succeeds (if admin has enabled this notification)

Subject: "Matching Complete for {exchange_name}"

Template Variables:

{
    "exchange_name": str,
    "participant_count": int,
    "exchange_date": datetime,
    "exchange_url": str
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Matching Complete! 🎉</h2>

<p>Participants have been successfully matched for <strong>{{ exchange_name }}</strong>.</p>

<p><strong>Details:</strong></p>
<ul>
    <li><strong>Participants Matched:</strong> {{ participant_count }}</li>
    <li><strong>Exchange Date:</strong> {{ exchange_date|format_date }}</li>
</ul>

<p>All participants have been notified of their assignments via email.</p>

<p style="text-align: center;">
    <a href="{{ exchange_url }}" class="button">View Exchange</a>
</p>
{% endblock %}

---

5. Data Purge Warning

Trigger: 7 days before exchange data is purged (30 days after completion)

Subject: "Data Purge Scheduled for {exchange_name}"

Template Variables:

{
    "exchange_name": str,
    "purge_date": datetime,
    "days_until_purge": int,
    "exchange_url": str
}

Content:

{% extends "emails/base.html" %}
{% block content %}
<h2>Data Purge Scheduled</h2>

<p>The exchange <strong>{{ exchange_name }}</strong> will be automatically deleted in <strong>{{ days_until_purge }} days</strong> ({{ purge_date|format_date }}).</p>

<p>All participant data, matches, and exchange details will be permanently removed as per the 30-day retention policy.</p>

<p>If you need to keep this data, please export it before the purge date.</p>

<p style="text-align: center;">
    <a href="{{ exchange_url }}" class="button">View Exchange</a>
</p>
{% endblock %}

Resend Integration

Configuration

import resend

class ResendClient:
    """Wrapper for Resend API."""

    def __init__(self, api_key: str):
        resend.api_key = api_key
        self.from_email = "noreply@sneakyklaus.app"  # Configured domain
        self.from_name = "Sneaky Klaus"

    def send_email(self, request: EmailRequest) -> EmailResult:
        """
        Send email via Resend API.

        Args:
            request: EmailRequest with to, subject, html, text

        Returns:
            EmailResult with success status and message ID
        """
        try:
            params = {
                "from": f"{self.from_name} <{self.from_email}>",
                "to": [request.to_email],
                "subject": request.subject,
                "html": request.html_body,
                "text": request.text_body,
            }

            # Optional: Add tags for tracking
            if request.tags:
                params["tags"] = request.tags

            response = resend.Emails.send(params)

            return EmailResult(
                success=True,
                message_id=response["id"],
                timestamp=datetime.utcnow()
            )

        except resend.exceptions.ResendError as e:
            logger.error(f"Resend API error: {str(e)}")
            return EmailResult(
                success=False,
                error=str(e),
                timestamp=datetime.utcnow()
            )

        except Exception as e:
            logger.error(f"Unexpected error sending email: {str(e)}")
            return EmailResult(
                success=False,
                error="Internal error",
                timestamp=datetime.utcnow()
            )

Email Request Model

@dataclass
class EmailRequest:
    """Email send request."""
    to_email: str
    subject: str
    html_body: str
    text_body: str
    tags: Optional[dict] = None  # For analytics/tracking

@dataclass
class EmailResult:
    """Email send result."""
    success: bool
    message_id: Optional[str] = None
    error: Optional[str] = None
    timestamp: datetime = field(default_factory=datetime.utcnow)

Email Tags (Optional)

For analytics and troubleshooting:

tags = {
    "type": "match_notification",
    "exchange_id": "123",
    "environment": "production"
}

Error Handling & Retries

Retry Strategy

def send_email_with_retry(request: EmailRequest, max_retries: int = 3) -> EmailResult:
    """
    Send email with exponential backoff retry.

    Args:
        request: EmailRequest to send
        max_retries: Maximum retry attempts

    Returns:
        EmailResult
    """
    from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type

    @retry(
        stop=stop_after_attempt(max_retries),
        wait=wait_exponential(multiplier=1, min=2, max=10),
        retry=retry_if_exception_type(resend.exceptions.ResendError)
    )
    def _send():
        return resend_client.send_email(request)

    try:
        return _send()
    except Exception as e:
        logger.error(f"Failed to send email after {max_retries} attempts: {str(e)}")
        return EmailResult(success=False, error=f"Failed after {max_retries} retries")

Failure Logging

All email send attempts logged to database for audit:

class EmailLog(db.Model):
    """Audit log for email sends."""
    id = db.Column(db.Integer, primary_key=True)
    to_email = db.Column(db.String(255), nullable=False)
    subject = db.Column(db.String(500), nullable=False)
    email_type = db.Column(db.String(50), nullable=False)
    success = db.Column(db.Boolean, nullable=False)
    message_id = db.Column(db.String(255), nullable=True)
    error = db.Column(db.Text, nullable=True)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)

Batch Email Sending

For sending to multiple recipients (e.g., match notifications):

def send_match_notifications_batch(self, exchange_id: int) -> BatchEmailResult:
    """
    Send match notifications to all participants in exchange.

    Args:
        exchange_id: Exchange ID

    Returns:
        BatchEmailResult with success count and failures
    """
    participants = Participant.query.filter_by(
        exchange_id=exchange_id,
        withdrawn_at=None
    ).all()

    results = []
    failed = []

    for participant in participants:
        result = self.send_match_notification(participant.id)
        results.append(result)

        if not result.success:
            failed.append({
                "participant_id": participant.id,
                "participant_email": participant.email,
                "error": result.error
            })

        # Rate limit: Small delay between sends
        time.sleep(0.1)

    return BatchEmailResult(
        total=len(participants),
        successful=len([r for r in results if r.success]),
        failed=len(failed),
        failures=failed
    )

Testing

Email Testing in Development

Option 1: Resend Test Mode

• Use Resend's test API key
• Emails sent to test mode, not delivered

Option 2: MailHog / MailCatcher

• Local SMTP server for testing
• View emails in web UI

Option 3: Mock in Unit Tests

from unittest.mock import patch

class TestNotificationService(unittest.TestCase):

    @patch('notification_service.ResendClient.send_email')
    def test_send_registration_confirmation(self, mock_send):
        mock_send.return_value = EmailResult(success=True, message_id="test-123")

        service = NotificationService()
        result = service.send_registration_confirmation(participant_id=1)

        self.assertTrue(result.success)
        mock_send.assert_called_once()

Integration Tests

class TestNotificationIntegration(TestCase):

    def test_full_match_notification_workflow(self):
        """Test complete match notification workflow."""
        # Setup
        exchange = create_test_exchange()
        participants = [create_test_participant(exchange) for _ in range(5)]
        execute_matching(exchange.id)

        # Execute
        service = NotificationService()
        result = service.send_match_notifications_batch(exchange.id)

        # Assert
        self.assertEqual(result.total, 5)
        self.assertEqual(result.successful, 5)
        self.assertEqual(result.failed, 0)

        # Verify emails logged
        logs = EmailLog.query.filter_by(email_type="match_notification").all()
        self.assertEqual(len(logs), 5)

Deliverability Best Practices

SPF, DKIM, DMARC

Configure DNS records for Resend domain:

• SPF: Authorize Resend to send on your behalf
• DKIM: Sign emails cryptographically
• DMARC: Define policy for failed authentication

Example DNS Configuration:

TXT @ "v=spf1 include:_spf.resend.com ~all"
CNAME resend._domainkey resend.domainkey.resend.com
TXT _dmarc "v=DMARC1; p=quarantine; rua=mailto:admin@example.com"

Unsubscribe Links

For reminder emails, include unsubscribe link:

unsubscribe_url = f"{app_url}/participant/exchange/{exchange_id}/edit"

Participants can disable reminders via profile edit.

Email Content Best Practices

1. Clear Subject Lines: Descriptive and concise
2. Plain Text Alternative: Always include text version
3. Inline CSS: Email clients strip external stylesheets
4. Mobile Responsive: Use responsive design techniques
5. Clear Call-to-Action: Prominent buttons/links
6. Avoid Spam Triggers: No all-caps, excessive punctuation, spam keywords

Performance Considerations

Asynchronous Sending

For non-critical emails, send asynchronously:

from threading import Thread

def send_email_async(email_request: EmailRequest):
    """Send email in background thread."""
    thread = Thread(target=lambda: notification_service.send_email(email_request))
    thread.start()

Note: For production, use proper background job queue (see background-jobs.md)

Rate Limiting

Resend has rate limits (depends on plan):

• Free: 100 emails/day
• Paid: Higher limits

Mitigation:

• Batch operations with delays between sends
• Implement queue for large batches
• Monitor usage and implement backoff

Security Considerations

Token Inclusion

Magic links and password reset tokens:

• URL Structure: {app_url}/auth/participant/magic/{token}
• Token Format: 32-byte random, base64url encoded
• Security: Tokens hashed in database, original never stored

Email Spoofing Prevention

• Use authenticated Resend domain
• Configure SPF/DKIM/DMARC
• Never allow user-controlled "from" addresses

Sensitive Data

• Never include: Passwords, full tokens (only links)
• Include only necessary: Participant names, gift ideas (expected in context)
• Audit log: Track all emails sent

Future Enhancements

1. HTML Email Builder: Visual template editor for admin
2. Localization: Multi-language email templates
3. A/B Testing: Test different email content for engagement
4. Analytics: Track open rates, click rates (Resend webhooks)
5. Custom Branding: Allow admin to customize email header/colors
6. Email Queue Dashboard: Admin view of pending/failed emails

References

• Resend Documentation
• Jinja2 Template Documentation
• Email Deliverability Best Practices
• Data Model Specification
• API Specification