Getting Started Core Concepts - onouyek/MailApe GitHub Wiki

Core Concepts

Understanding the essential concepts and terminology in MailApe.

Domain Model

Mailing List

A mailing list is the central concept in MailApe. It represents a collection of subscribers who will receive messages.

Key Properties:

  • Owner: The user who created and manages the list
  • Name: Display name for the mailing list
  • Unique ID: UUID for secure identification

Business Rules:

  • Only the owner can manage the mailing list
  • Only the owner can send messages to the list

Source: models.py#L10-23

Subscriber

A subscriber represents an email address that has requested to receive messages from a mailing list.

Key Properties:

  • Email: The subscriber's email address
  • Confirmed: Whether the subscription has been confirmed
  • Mailing List: Which list they're subscribed to

Business Rules:

  • Each email can only subscribe once per mailing list
  • Subscribers must confirm their subscription via email
  • Only confirmed subscribers receive messages

Confirmation Flow:

  1. User submits email to subscribe
  2. System creates subscriber with confirmed=False
  3. Confirmation email is sent automatically
  4. User clicks confirmation link
  5. Subscriber status becomes confirmed=True

Source: models.py#L33-62

Message

A message represents content that will be sent to all confirmed subscribers of a mailing list.

Key Properties:

  • Subject: Email subject line
  • Body: Email content
  • Mailing List: Which list receives the message
  • Timestamps: When sending started and finished

Business Rules:

  • Messages are automatically queued for delivery when created
  • Only confirmed subscribers receive the message
  • Individual delivery is tracked per subscriber

Source: models.py#L64-84

Subscriber Message

A subscriber message represents an individual email delivery to a specific subscriber.

Key Properties:

  • Message: The content being sent
  • Subscriber: The recipient
  • Delivery Status: When created, attempted, and sent
  • Timestamps: Tracking delivery lifecycle

Purpose:

  • Individual delivery tracking
  • Retry failed deliveries
  • Audit trail for email sending

Source: models.py#L97-122

Email Processing Workflow

1. Subscription Process

graph LR
    A[User Submits Email] --> B[Create Unconfirmed Subscriber]
    B --> C[Send Confirmation Email]
    C --> D[User Clicks Link]
    D --> E[Subscriber Confirmed]

2. Message Distribution Process

graph TD
    A[Owner Creates Message] --> B[Message Saved]
    B --> C[Build Subscriber Messages Task]
    C --> D[Create SubscriberMessage for Each Confirmed Subscriber]
    D --> E[Queue Individual Send Tasks]
    E --> F[Send Email to Each Subscriber]

Task Queue System

MailApe uses Celery for asynchronous email processing to ensure:

Benefits:

  • Web interface remains responsive
  • Email sending doesn't block user actions
  • Failed emails can be retried
  • Bulk email sending is handled efficiently

Key Tasks:

  • send_confirmation_email_to_subscriber: Send subscription confirmation
  • build_subscriber_messages_for_message: Create individual message records
  • send_subscriber_message: Send email to individual subscriber

Source: models.py#L60-61, L83, L121

Authentication and Authorization

User Management

  • Uses Django's built-in User model
  • Registration and login functionality
  • Password management

Access Control

  • Mailing List Access: Only owners can manage their lists
  • Message Sending: Only list owners can send messages
  • Subscriber Management: Automatic via web interface

Implementation:

def user_can_use_mailing_list(self, user):
    return user == self.owner

Source: models.py#L21-22

Data Integrity

Unique Constraints

  • One subscription per email per mailing list
  • Prevents duplicate subscriptions

UUID Usage

  • All models use UUID primary keys
  • Provides security and prevents enumeration attacks

Confirmation Requirements

  • Double opt-in subscription process
  • Ensures legitimate email addresses
  • Complies with email marketing best practices

API Design

MailApe includes a REST API built with Django REST Framework:

Features:

  • Rate limiting (60/min for authenticated, 30/min for anonymous)
  • Authentication required for most endpoints
  • Throttling to prevent abuse

Source: common_settings.py#L125-132

Next Steps