https://github.com/izadoesdev/mailbuddy
AI-powered email parsing, classification, and semantic search — built for devs managing massive inboxes.
https://github.com/izadoesdev/mailbuddy
Last synced: about 17 hours ago
JSON representation
AI-powered email parsing, classification, and semantic search — built for devs managing massive inboxes.
- Host: GitHub
- URL: https://github.com/izadoesdev/mailbuddy
- Owner: izadoesdev
- License: mit
- Created: 2025-04-07T20:15:26.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-12-07T12:04:58.000Z (7 months ago)
- Last Synced: 2026-07-07T13:29:17.617Z (3 days ago)
- Language: TypeScript
- Homepage: https://www.mailbuddy.dev
- Size: 6.36 MB
- Stars: 24
- Watchers: 1
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 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)
```bash
# 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
```bash
# 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:
```env
# 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:
```plaintext
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.modify
```
### Setting up Google Credentials
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
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`:
```env
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
```
### Environment Variables
Add these to your `.env.local`:
```env
# 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](https://nextjs.org/)
- [Once UI](https://once-ui.com/)
- [Gmail API](https://developers.google.com/gmail/api)
- [Prisma](https://www.prisma.io/)
---