Mail0.io

An Open-Source Gmail Alternative for the Future of Email

Table of Content

• What is Mail0.io?
• Why Mail0.io?
• Our Mission
• Documentation
• Roadmap 🛤️
  • 1. Core Email Connectivity
  • 2. Email Usage Improvements
  • 3. Infrastructure
• Development Priorities
• Join the Movement 🚀
  • Stay Tuned
• Tech Stack
• Getting Started
  • Prerequisites
  • Environment Variables
  • Running Locally
• Contribute
• Issues
  • Create a new issue
  • Solve an issue
• Pull Request
• License

What is Mail0.io?

Mail0.io is an open-source email solution that gives users the power to self-host their own email app while also integrating external services like Gmail and other email providers. Our goal is to put control, privacy, and customization back into the hands of users—whether they choose to host their email independently or manage multiple inboxes from a single, customizable platform.

Why Mail0.io?

Most email services today are either closed-source, data-hungry, or too complex to self-host. Mail0.io is different:

✅ Fully Open-Source – No hidden agendas, no walled gardens. 100% transparency. 🔒 Data Privacy First – Your emails, your data. No tracking, no selling, no middlemen. ⚙️ Self-Hosting Freedom – Run your own email app with ease. 📬 Unified Inbox – Connect multiple email providers like Gmail, Outlook, and more. 🎨 Customizable UI & Features – Tailor your email experience the way you want it. 🚀 Developer-Friendly – Built with extensibility and integrations in mind.

Our Mission

We believe email should be:

1. Yours – You control where your data is stored.
2. Flexible – Use it however you want—self-hosted or connected to third-party providers.
3. Open – Transparent development, open collaboration, and community-driven innovation.
4. User-Friendly – No need for technical expertise to get started.

Documentation

• License - Project license and terms
• Roadmap - Development plans and future features

Roadmap 🛤️

This document outlines the development roadmap for Mail0.io. Our vision is to create a powerful, user-friendly, and privacy-focused email experience.

1. Core Email Connectivity

• Connect main email providers
• Support for multiple email accounts
• Unified inbox experience

2. Email Usage Improvements

• AI-powered email assistance
• Advanced drag-and-drop tools
• Customizable keyboard shortcuts
• Performance optimization
• Enhanced search capabilities
• Deep customization options

3. Infrastructure

• Domain management
• Optimized email client
• Self-hosting capabilities

Development Priorities

1. Building a robust foundation for email management
2. Implementing user-requested features
3. Ensuring seamless integration with existing email providers
4. Maintaining high performance and reliability

We welcome community input and contributions to help shape these features and priorities. If you have suggestions or would like to contribute, please:

1. Open an issue to discuss new feature ideas
2. Submit pull requests for improvements
3. Join discussions in existing issues

This roadmap is a living document and will be updated as development progresses and priorities evolve based on community feedback and technological advances.

Join the Movement 🚀

Mail0.io is not just another email app—it's a vision for a better, more open, and user-controlled email ecosystem. If you believe in privacy, open-source software, and giving users control, we'd love for you to join us!

📢 Follow our progress – Stay updated on GitHub as we build Mail0.io. 💡 Contribute – Share your ideas, suggest features, and help shape the project. 🤝 Community-driven – Our goal is to create an email solution for the people, by the people.

Stay Tuned

We're just getting started. If you're excited about a future where email belongs to users, not corporations, let's make it happen together.

---

🤍 Mail0.io – Email, Reimagined.

Tech Stack

Mail0.io is built with modern and reliable technologies:

• Frontend: Next.js, React, TypeScript, TailwindCSS, Shadcn UI
• Backend: Node.js, Drizzle ORM
• Database: PostgreSQL
• Authentication: Better Auth, Google OAuth

Getting Started

Prerequisites

Required Versions:

• Node.js >= 18.0.0
• pnpm >= 8.0.0
• Docker >= 20.10.0

Before running the application, you'll need to set up several services and environment variables:

1. Setup Local Services with Dev Container and Docker

   • Make sure you have Docker, NodeJS, and pnpm installed.

   • Open codebase as a container in VSCode or your favorite VSCode fork.

   • Run the following commands in order to populate your dependencies and setup docker

     pnpm install
     pnpm docker:up
     

   • Run the following commands to clean up after yourself

     pnpm docker:down
     rm -rf node_modules
     rm pnpm-lock.yaml
     

   • Run the following commands if you are unable to start any of the services

     rm -rf node_modules
     rm pnpm-lock.yaml
     

2. Better Auth Setup

   • Open .env and change the BETTER_AUTH_SECRET to a random string. (Use openssl rand -hex 32 to generate a 32 character string)

     BETTER_AUTH_SECRET=your_secret_key

3. Google OAuth Setup

   • Go to Google Cloud Console

   • Create a new project

   • Add the following APIs to your Google Cloud Project: People API, Gmail API

     • Use links above and click 'Enable' or
     • Go to 'APIs and Services' > 'Enable APIs and Services' > Search for 'Google People API' and click 'Enable'
     • Go to 'APIs and Services' > 'Enable APIs and Services' > Search for 'Gmail API' and click 'Enable'

   • Enable the Google OAuth2 API

   • Create OAuth 2.0 credentials (Web application type)

   • Add authorized redirect URIs:

     • Development:
       • http://localhost:3000/api/auth/callback/google
       • http://localhost:3000/api/v1/mail/auth/google/callback
     • Production:
       • https://your-production-url/api/auth/callback/google
       • https://your-production-url/api/v1/mail/auth/google/callback

   • Add to .env:

     GOOGLE_CLIENT_ID=your_client_id
     GOOGLE_CLIENT_SECRET=your_client_secret
     GOOGLE_REDIRECT_URI=http://localhost:3000/api/v1/mail/auth/google/callback

   • Add yourself as a test user:

     • Goto Audience
     • Under 'Test users' click 'Add Users'
     • Add your email and click 'Save'

Warning

The GOOGLE_REDIRECT_URI must match exactly what you configure in the Google Cloud Console, including the protocol (http/https), domain, and path - these are provided above.

4. Github OAuth Setup

   • Go to Github Developer Setting

   • Create a new OAuth Apps

   • Add authorized redirect URIs:

     • Development:
       • http://localhost:3000/api/auth/callback/github
     • Production:
       • https://your-production-url/api/auth/callback/github

   • Add to .env:

     GITHUB_CLIENT_ID=your_client_id
     GITHUB_CLIENT_SECRET=your_client_secret

Environment Variables

Copy .env.example to .env and configure the following variables:

# Auth
BETTER_AUTH_SECRET=     # Required: Secret key for authentication

# Google OAuth (Optional)
GOOGLE_CLIENT_ID=       # Required for Gmail integration
GOOGLE_CLIENT_SECRET=   # Required for Gmail integration
GOOGLE_REDIRECT_URI=    # Required for Gmail integration

# Database
DATABASE_URL=          # Required: PostgreSQL connection string

Update the PostgreSQL database accordingly

Drizzle will apply the schema migrations set in .env

pnpm db:push

• Use pnpm db:studio to view and manage your data

Running Locally

Run the development server:

pnpm dev

Open http://localhost:3000 with your browser to see the result.

Contribute

1. You can fork the repository and make your changes on your forked repository. Once you have made your changes, you can create a pull request to the main branch.
2. To add code to the main branch, make a pull request. Your code should always be reviewed by a partner, not yourself!

Issues

Create a new issue

If you spot a problem with the docs, search if an issue already exists. If a related issue doesn't exist, you can open a new issue using a relevant issue form.

Solve an issue

Scan through our existing issues to find one that interests you. You can narrow down the search using labels as filters. See "Label reference" for more information. As a general rule, we don't assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.

Pull Request

When you're finished with the changes, create a pull request, also known as a PR.

• Fill the "Ready for review" template so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request.
• Don't forget to link PR to issue if you are solving one.
• Enable the checkbox to allow maintainer edits so the branch can be updated for a merge. Once you submit your PR, a reviewer will review your proposal. We may ask questions or request additional information.
• We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
• As you update your PR and apply changes, mark each conversation as resolved.
• If you run into any merge issues, checkout this git tutorial to help you resolve merge conflicts and other issues.

License

Mail0.io is licensed under the MIT License. This means you can:

✅ Use the software commercially ✅ Modify the source code ✅ Distribute your modifications ✅ Use and modify the software privately

The only requirement is that you include the original copyright and license notice in any copy of the software/source.

See the LICENSE file for the full license text.