MBOX Viewer

A modern, desktop-optimized email viewer for MBOX files built with Next.js and NextUI.

Features

• Modern UI: Clean, responsive interface optimized for desktop use
• Multiple MBOX Support: Load and browse multiple MBOX files
• Rich Email Display: View all email metadata, headers, and content
• Content Rendering: Support for both plain text and HTML emails
• Attachment Handling: Preview and download email attachments
• Search & Filter: Powerful search and filtering capabilities
• Theme Support: Light and dark theme modes
• Three-Panel Layout: File browser, email list, and detail view

Getting Started

Prerequisites

• Node.js 18.0 or higher
• npm or yarn package manager

Installation

1. Clone or download this repository

2. Install dependencies:

   npm install

3. Place your MBOX files in the mbox-files directory (created automatically)

4. Start the development server:

   npm run start:dev

5. Open your browser and navigate to http://localhost:4000

Production Build

npm run build
npm start:prod

Configuration

MBOX Directory

By default, the application looks for MBOX files in the ./mbox-files directory. You can change this by setting the MBOX_DIRECTORY environment variable:

# In .env.local
MBOX_DIRECTORY=/path/to/your/mbox/files

Port Configuration

The application runs on port 4000 by default. You can change this in the package.json scripts or by setting the PORT environment variable.

MBOX File Format

MBOX is a standard mailbox format where:

• Messages are stored in a single text file
• Each message starts with a "From " line
• Messages are separated by blank lines

Supported MBOX Variants

• Standard MBOX format
• Files with .mbox extension
• Files with .mbx extension
• Files without extension (detected by content)

Architecture

Frontend

• Next.js 14: React framework with App Router
• NextUI: Modern React UI library
• Tailwind CSS: Utility-first CSS framework
• Lucide React: Beautiful icon library
• TypeScript: Type-safe development

Backend

• Next.js API Routes: Server-side email parsing
• Mailparser: Robust email parsing library
• iconv-lite: Character encoding support
• Node.js fs: File system operations

Key Components

1. FileList: Browse and select MBOX files
2. EmailList: Display paginated email list with search
3. EmailDetail: Rich email content viewer with tabs
4. MboxParser: Server-side MBOX parsing utility

Email Data Structure

The application extracts and displays:

• Headers: From, To, CC, BCC, Subject, Date, Message-ID
• Content: Plain text and HTML body content
• Attachments: Files with preview and download support
• Metadata: Message size, priority, thread information
• Raw Data: Complete email source when needed

Performance Considerations

• Pagination: Large MBOX files are loaded in chunks
• Lazy Loading: Email content loaded on demand
• Caching: Parsed email metadata is cached
• Streaming: Large files processed incrementally

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Security Features

• Path Validation: Prevents directory traversal attacks
• Content Sanitization: XSS protection for email content
• File Type Validation: Restricts access to MBOX files only
• Error Boundaries: Graceful error handling

Troubleshooting

Common Issues

1. No MBOX files found

   • Check that files are in the correct directory
   • Verify file extensions (.mbox, .mbx, or no extension)
   • Ensure files contain valid MBOX format

2. Parsing errors

   • Check file encoding (UTF-8 recommended)
   • Verify MBOX format compliance
   • Look for corrupted message boundaries

3. Performance issues

   • Reduce email batch size in settings
   • Check available system memory
   • Consider splitting large MBOX files

Debug Mode

Enable debug logging by setting:

NODE_ENV=development

Development

Project Structure

mbox-viewer/
├── app/             # Next.js app directory
│   ├── api/         # API routes
│   ├── components/  # React components
│   ├── types/       # TypeScript definitions
│   └── globals.css  # Global styles
├── lib/             # Utility libraries
├── mbox-files/      # MBOX files directory
└── public/          # Static assets

Scripts

• npm run start:dev: Development server
• npm run build: Production build
• npm run start:prod: Production server
• npm run cq:lint: Code linting
• npm run cq:type-check: TypeScript checking
• npm run cq:format: Prettier formatting
• npm run cq: Code quality operations

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is open source and available under the MIT License.

Acknowledgments

• NextUI team for the beautiful component library
• Mailparser contributors for robust email parsing
• Next.js team for the excellent React framework
• Lucide for the clean icon set

---

Note 1: This application is designed for viewing email archives and does not support sending emails or connecting to live email servers. It's perfect for analyzing exported email data, migrating between email systems, or forensic email analysis.

Note 2: The fundamentals of this application have been generated with GitHub Copilot Agent Mode using Claude Sonnet 4. Parts of the code have been revised and manually upgraded, however, most of it has been generated as the goal of this tool is to serve a very specific functionality in a straightforward manner. Future contributions to this repository must take this notice into account in order (if the time comes) to make a robust web application out of this.