Skip to content

Latest commit

 

History

History
281 lines (203 loc) · 9.74 KB

README.md

File metadata and controls

281 lines (203 loc) · 9.74 KB

Zero Logo

Zero

Deploy with Vercel

An Open-Source Gmail Alternative for the Future of Email

What is Zero?

Zero is an open-source AI 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 modernize and improve emails through AI agents to truly modernize emails.

Why Zero?

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

  • ✅ Open-Source – No hidden agendas, fully transparent.
  • 🦾 AI Driven - Enhance your emails with Agents & LLMs.
  • 🔒 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.

Tech Stack

Zero 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:

Before running the application, you'll need to set up services and configure environment variables. For more details on environment variables, see the Environment Variables section.

Setup Options

You can set up Zero in two ways:

Option 1: Standard Setup (Recommended)

Quick Start Guide

  1. Clone and Install

    # Clone the repository
git clone https://github.com/Mail-0/Zero.git
cd Mail-0

# Install dependencies
pnpm install

# Install database dependencies
pnpm db:dependencies

# Start database locally
pnpm docker:up

  2. Set Up Environment

    • Copy .env.example to .env in both apps/mail and packages/db folders
    • Configure your environment variables (see below)
    • Install database dependencies: pnpm db:dependencies
    • Initialize the database: pnpm db:push

  3. Start the App

    pnpm dev

  4. Open in Browser

    Visit http://localhost:3000

Option 2: Dev Container Setup (For VS Code Users)

This option uses VS Code's Dev Containers feature to provide a fully configured development environment with all dependencies pre-installed. It's great for ensuring everyone on the team has the same setup.

  1. Prerequisites

  2. Open in Dev Container

    • Clone the repository: git clone https://github.com/Mail-0/Zero.git
    • Open the folder in VS Code
    • When prompted, click "Reopen in Container" or run the "Dev Containers: Open Folder in Container" command
    • VS Code will build and start the dev container (this may take a few minutes the first time)

  3. Access the App

  4. Troubleshooting

    • If you encounter issues with the container, try rebuilding it using the "Dev Containers: Rebuild Container" command
    • For dependency issues inside the container: 
      rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

Environment Setup

  1. Better Auth Setup

    • Open the .env file 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

  2. Google OAuth Setup (Required for Gmail integration)

    • Go to Google Cloud Console

    • Create a new project

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

      • Use the 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:

      • Go to 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.

  1. GitHub OAuth Setup (Optional)

    Click to expand GitHub OAuth setup instructions

    • Go to GitHub Developer Setting

    • Create a new OAuth App

    • 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 located in the apps/mail folder to .env in the same folder and configure the following variables:

# Auth
BETTER_AUTH_SECRET=     # Required: Secret key for authentication

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

# GitHub OAuth (Optional)
GITHUB_CLIENT_ID=       # Optional: For GitHub authentication
GITHUB_CLIENT_SECRET=   # Optional: For GitHub authentication

# Database
DATABASE_URL=           # Required: PostgreSQL connection string for backend connection

# Redis
REDIS_URL=              # Redis URL for caching (http://localhost:8079 for local dev)
REDIS_TOKEN=            # Redis token (upstash-local-token for local dev)

To be able to run pnpm db:push and push the schemas to the database you also have to add a .env file to the packages/db folder (so packages/db/.env) with the following content:

DATABASE_URL=          # Required: PostgreSQL connection string for migrations

For local development a connection string example is provided in the .env.example file located in the same folder as the database.

Note: The DATABASE_URL connection string in the apps/mail/.env has to be the same as the one in packages/db/.env

Database Setup

Zero uses PostgreSQL for storing data. Here's how to set it up:

  1. Start the Database

    Run this command to start a local PostgreSQL instance:

    pnpm docker:up

    This creates a database with:

    • Name: zerodotemail
    • Username: postgres
    • Password: postgres
    • Port: 5432

  2. Set Up Database Connection

    Make sure your database connection string is in:

    • apps/mail/.env
    • packages/db/.env

    For local development use:

    DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zerodotemail"

  3. Database Commands

    • Install database dependencies:

      pnpm db:dependencies

    • Set up database tables:

      pnpm db:push

    • Create migration files (after schema changes):

      pnpm db:generate

    • Apply migrations:

      pnpm db:migrate

    • View database content:

      pnpm db:studio

Contribute

Please refer to the contributing guide.

Star History

Star History Chart