MailCroc

The Ultimate Real-Time Disposable Email Service

Features • Architecture • Getting Started • Usage • Deployment

---

MailCroc is a next-generation temporary email service built for privacy, speed, and modern web standards. Unlike traditional temp mail services that are riddled with ads and delays, MailCroc offers a premium, ad-free experience with instant WebSocket delivery, AI-powered tools, and end-to-end password protection.

It relies on a serverless architecture, using Cloudflare Email Workers to ingest emails and GitHub as a free, high-tier storage solution.

🎥 Watch the Demo

MAILCROC DEMO VIDEO - Watch Video

🚀 Key Features

🛡️ Privacy & Security

• 🔐 Password Protected Emails: Send encrypted emails to external addresses (Gmail/Outlook) via a secure web portal. Only accessible with your shared code.
• 🔒 Instant Session Isolation: Each session is 100% private. Emails are tied to a unique sessionId, ensuring no cross-user visibility.
• 🧹 Instant Clean (Auto-Wipe): A dedicated toggle that permanently deletes all mail (sent & received) the moment you close the tab or refresh.
• 💓 Heartbeat Protection: Active sessions are protected by a live heartbeat. If you're using an ID, no one else can claim it.
• Zero Logs: We do not store IP addresses or browser fingerprints.

🤖 AI-Powered Intelligence

• Help me write (Smart Compose): Generate professional replies or new emails instantly using our integrated AI engine (Powered by OpenRouter & Puter.js).
• Smart Summarization: Get the gist of long emails with one click.
• Extract Details: AI can intelligently extract receipts, meeting times, and key details from threads.
• Vision & Voice: Extract text from attached images and have your emails read aloud by professional AI voices (ElevenLabs).

⚡ Real-Time Experience

• Instant Delivery: Emails appear in your inbox milliseconds after they are received via Socket.IO.
• ✨ Lottie Notifications: Beautiful, real-time animations and "Correct Answer" sounds alert you the moment a new mail arrives.
• Live UI Updates: The interface updates instantly. No more hitting the refresh button.

📧 Advanced Email Capabilities

• Reply & Compose: Full support for sending new emails and replying to received ones.
• Universal Attachments: Send and receive files (Images, PDFs, Docs, Audio, Video, Archives).
• Export Options: One-click export of emails to PDF, Markdown, or JSON.
• Address Variations: Generate standard aliases, +tags, dot-tricks, and custom handles.

💻 Modern UI/UX

• Premium Design: Features stunning micro-animations (Lottie), dynamic layout, and glassmorphism.
• PWA Support: Installable as a native-like app on iOS, Android, and Desktop with offline support.
• Draggable Compose: A dynamic, draggable workspace for multitasking.
• Unified Dashboard: Monitor system health directly from the built-in status page.
• Offline Mode: View previously loaded emails even without an internet connection.

🏗️ Architecture

MailCroc operates on a 100% serverless infrastructure, ensuring high availability and zero maintenance costs.

graph TD
    subgraph Client
        Browser[User Browser / PWA]
        AI[OpenRouter/Puter AI Engine]
    end

    subgraph Serverless_Core
        Vercel[Next.js on Vercel]
        CF_Worker[Cloudflare Ingress & Relay]
    end

    subgraph Storage
        GitHub_Repo[Live JSON Store]
    end

    %% Flows
    Browser <-->|HTTPS| Vercel
    CF_Worker -->|Webhook| Vercel
    Vercel -->|Commit| GitHub_Repo
    Browser <-->|AI Tasks| AI

Loading

🛠️ Tech Stack

• Framework: Next.js 14+ (App Router)
• Language: TypeScript
• AI Engine: OpenRouter, ElevenLabs, Puter.js
• Animations: Lottie (via lottie-react), Framer Motion
• Real-time: Socket.IO
• Deployment: Vercel & Cloudflare Workers

🏁 Getting Started

Prerequisites

• Node.js 18+
• A generic GitHub account (for serverless DB storage)
• Cloudflare account (for email ingress routing)
• OpenRouter API Key (for backend AI)

Local Development

1. Clone the repository

   git clone https://github.com/cybe4sent1nel/mailcroc.git
   cd mailcroc

2. Install Dependencies

   cd mailcroc-app
   npm install

3. Run the App

   npm run dev:all

   This starts the Next.js frontend and the local mail server concurrently. Visit http://localhost:3000.

📦 Deployment

Vercel (Frontend & API)

1. Push code to GitHub and import to Vercel/Render.
2. Set the Root Directory to mailcroc-app.
3. Add GITHUB_TOKEN, GITHUB_REPO_OWNER, and GITHUB_REPO_NAME to Env Vars.

Cloudflare (Email Ingress)

1. Deploy the worker in mailcroc-worker/ via npx wrangler deploy.
2. Route your domain's email traffic to the worker in the Cloudflare Dashboard under Email Routing rules.

📖 Usage Guide

1. Generate Identity: Select an identity type (Standard, Plus, Dot, or Gmail).
2. Secure Your Mail: Toggle "Password Protection" in the compose modal to send an encrypted link.
3. Use AI: Click "Help me write" in the compose window to generate content instantly.
4. Export: Use the export dropdown to save emails as PDF or Markdown.
5. Technical Deep Dive: Refer to ARCHITECTURE.md for detailed system logic and library details.

---

Designed and developed by Fahad Khan