Mailbuddy - Your Secure AI Email Companion

A modern, secure, and privacy-focused email client with Gmail integration

Features • Security • Getting Started • Tech Stack • Roadmap • License

🌟 Overview

Mailbuddy is a sophisticated email client focusing on security, privacy, and user experience. It combines Gmail's powerful API with client-side encryption to ensure your emails remain private while providing a clean, intuitive interface.

Why Mailbuddy?

• Privacy First: Your emails are encrypted with keys only you can access
• Modern Interface: Clean, fast UI built with Next.js and Once UI
• Seamless Integration: Works with your existing Gmail account
• Smart Features: AI-powered email categorization and priority sorting
• Fully Open Source: Transparent, community-driven development

🔑 Key Features

🔐	Zero-Knowledge Architecture - Your emails are encrypted with keys only you control
⚡	Lightning-Fast Experience - Background syncing and optimized performance
🧠	AI-Enhanced Organization - Smart email categorization and priority detection
🔄	Real-Time Syncing - Changes reflect immediately across devices
🧵	Threaded Conversations - Emails organized into meaningful threads

🔒 Security

User-Specific Encryption

Each user gets their own unique encryption key that secures their email data:

• Client-Side Encryption: All sensitive data is encrypted before server storage
• User-Controlled Keys: Only you can decrypt and access your email content
• Data Isolation: Even in a breach, emails remain secure and unreadable
• Zero Server Access: The server never sees the unencrypted content of your emails

Encrypted Fields

• ✓ Email body content
• ✓ Email subject lines
• ✓ Email snippets/previews
• ✓ Sender and recipient information

Compliance Ready

Our architecture is designed to help maintain compliance with:

• GDPR
• CCPA
• HIPAA (with proper configuration)

🚀 Getting Started

Using Docker Compose (Recommended)

# Start the required services
docker compose up -d

# The following services will be available:
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379
# - Qdrant Vector DB: localhost:6333

Manual Setup

# Clone the repository
git clone https://github.com/izadoesdev/mailer

# Navigate to project directory
cd Mailbuddy

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env.local
# Fill in required environment variables

# Generate the prisma client & push the schema to your local database
bunx prisma db push

# Start development server
bun run dev

Environment Setup

Create a .env.local file with the following variables:

# Database
DATABASE_URL="postgresql://mailbuddy:mailbuddy@localhost:5432/mailbuddy"

# Redis
REDIS_URL="redis://localhost:6379"

# Other variables as specified in .env.example

🔐 Gmail API Setup

Required Scopes

The following Gmail API scopes are required for full functionality:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.modify

Setting up Google Credentials

1. Go to Google Cloud Console
2. Create or select a project
3. Go to OAuth Consent Screen:
   • Set user type to "External"
   • Fill in basic app info (for testing)
4. Go to APIs & Services → Credentials
5. Create OAuth 2.0 Client ID:
   • App type: Web
   • Add authorized redirect URIs:

     http://localhost:3000/api/auth/callback/google
     

6. Download the credentials JSON file
7. Add the following to your .env.local:

   GOOGLE_CLIENT_ID=your_client_id
   GOOGLE_CLIENT_SECRET=your_client_secret

Environment Variables

Add these to your .env.local:

# Gmail API
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

🛠️ Tech Stack

Frontend	Backend	Database	AI/ML
• Next.js • React • Once UI • TailwindCSS	• Next.js API Routes • Prisma ORM • BetterAuth • Gmail API	• PostgreSQL • Vector storage • Prisma migrations	• Email categorization • Priority detection • Smart summaries • Semantic search

📊 Application Architecture

├── src/
│   ├── app/                  # Next.js App Router
│   │   ├── api/              # API routes including inbox and Gmail integration
│   │   ├── auth/             # Authentication pages
│   │   ├── inbox/            # Email inbox views
│   │   ├── ai/               # AI processing for emails
│   │   ├── components/       # Reusable UI components
│   │   ├── libs/             # Utility functions and services
│   │   │   ├── auth/         # Authentication configuration
│   │   │   ├── db/           # Database configuration
│   │   │   ├── utils/        # Utilities including encryption
│   ├── prisma/               # Database schema and migrations
│   └── public/               # Static assets

📄 Documentation

• Complete API reference
• Database schema details
• Security implementation guide
• Customization options
• Contributing guidelines

🛣️ Roadmap

• Custom Folders & Labels: Create and manage custom organization
• Enhanced Search: Full-text and semantic search capabilities
• Mobile Applications: Native apps for iOS and Android
• Offline Mode: Full functionality without internet connection
• End-to-End Encryption: Secure email sending between Mailbuddy users
• Calendar Integration: View and manage events alongside emails

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE.txt for more information.

🙏 Acknowledgements

• Next.js
• Once UI
• Gmail API
• Prisma

---

Made with ❤️ by the Mailbuddy Team

Report Bug • Request Feature