Posta

Posta is a lightweight, secure, and fully-owned private email system designed explicitly for sending and receiving plain-text messages instantly between @subhr.in addresses.

🎯 Purpose

The primary goal of Posta is to serve as a hands-on reference implementation of a complete mail system. It bridges the gap between simple "send-an-email" tutorials and bloated internet-scale mail servers (like Postfix) by building the core components—SMTP handling, async delivery queue, mailbox architecture, and database isolation—from the ground up.

Posta is intentionally closed, private, and non-federated. It does not interface with the open internet (e.g., Gmail or Outlook) to avoid the immense complexity of spam filtering, DKIM, SPF, and DMARC verification, focusing entirely on systems-design learning and robust local delivery.

---

🏗️ Architecture

Posta splits the responsibilities strictly between a lightweight frontend and a powerful C backend:

graph TD
    Browser[Client Browser]
    Clerk[Clerk Auth Provider]
    Frontend[Next.js Frontend\nhttps://posta.subhr.in]
    Nginx[Nginx Reverse Proxy]
    CBackend[C Mail Server / Backend :8080 / :2525\nhttps://api.mail.subhr.in]
    PostgreSQL[(PostgreSQL :5433)]

    Browser -- 1. Logs in & Gets JWT --> Clerk
    Browser -- 2. Serves App --> Frontend
    Browser -- 3. API Request + Bearer JWT --> Nginx
    Nginx -- 4. Proxies --> CBackend
    CBackend -- 5. Verifies JWT / Handles DB Ops --> PostgreSQL

1. Frontend (Next.js)

• URL: https://posta.subhr.in
• Stack: Next.js App Router, JavaScript, Tailwind CSS.
• Authentication: Managed by Clerk client-side. The frontend fetches a session JWT using Clerk's getToken() and passes it in the Authorization: Bearer <JWT> header.
• Database Access: Zero database access. The frontend communicates exclusively with the C backend via APIs. No database secrets or configurations reside on the frontend.

2. Backend (C Mail Server)

• URL: https://api.mail.subhr.in
• Stack: Pure C, systemd service, Nginx reverse proxy.
• Network Ports:
  • HTTP API (8080): Serves mail operations (Inbox, Sent, Drafts, Trash, Send/Compose).
  • SMTP Ingestion (2525): Standard mail ingestion port allowing raw command submission (e.g., via telnet or nc).
• Authentication & Provisioning:
  • Validates the RS256 JWT signature using Clerk's public PEM key.
  • Extracts the Clerk user ID (sub claim) from the token.
  • Automatically provisions the user and default mailboxes (Inbox, Sent, Drafts, Trash) in PostgreSQL upon their first authenticated request.

3. Database (PostgreSQL)

• Access: Bound to localhost (127.0.0.1:5433). The C backend is the only entity that communicates with the database.
• Schema Core Tables:
  • users
  • mailboxes
  • messages
  • message_recipients
  • mailbox_messages
  • message_queue

---

🚀 Core Features

• Authentication & Registration: Restrained to the @subhr.in domain.
• Complete Mailboxes: Inbox, Sent, Drafts, and Trash.
• Interactive Operations: Read, reply, soft-delete (move to trash), and compose messages.
• SMTP Ingestion: Supports raw SMTP command ingestion directly through port 2525.
• Asynchronous Queue: Includes a robust message queue and delivery worker written in C that handles transient delivery failures and retries before marking messages as failed.
• Search: Full-text mail search within the user's mailboxes.