Inbox Zero - your 24/7 AI email assistant

Organizes your inbox, pre-drafts replies, and tracks follow‑ups - so you reach inbox zero faster. Open source alternative to Fyxer, but more customisable and secure.
Website · Discord · Issues

Mission

To help you spend less time in your inbox, so you can focus on what matters.

Features

• AI Personal Assistant: Organizes your inbox and pre-drafts replies in your tone and style.
• Cursor Rules for email: Explain in plain English how your AI should handle your inbox.
• Reply Zero: Track emails to reply to and those awaiting responses.
• Smart Categories: Automatically categorize every sender.
• Bulk Unsubscriber: One-click unsubscribe and archive emails you never read.
• Cold Email Blocker: Auto‑block cold emails.
• Email Analytics: Track your activity and trends over time.

Learn more in our docs.

Feature Screenshots

Demo Video

Built with

• Next.js
• Tailwind CSS
• shadcn/ui
• Prisma
• Upstash
• Turborepo

Star History

Feature Requests

To request a feature open a GitHub issue, or join our Discord.

Getting Started

We offer a hosted version of Inbox Zero at https://getinboxzero.com.

Self-Hosting with Docker

The easiest way to self-host Inbox Zero is using our pre-built Docker image.

See our Docker Self-Hosting Guide for complete instructions.

Local Development Setup

Here's a video on how to set up the project. It covers the same steps mentioned in this document. But goes into greater detail on setting up the external services.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.0.0
• Docker desktop (recommended for running Postgres and Redis)

Quick Start

1. Start the database and Redis (recommended):

   docker compose -f docker-compose.dev.yml up -d
   

   This starts Postgres and Redis in Docker containers. Alternatively, you can use your own Postgres/Redis instances.

2. Install dependencies and set up the database:

   pnpm install
   cd apps/web
   cp .env.example .env
   # Edit .env with your configuration
   pnpm prisma migrate dev
   

3. Run the development server:

   pnpm dev
   

The app will be available at http://localhost:3000.

Detailed Setup

Make sure you have the above installed before starting.

The external services that are required are (detailed setup instructions below):

• Google OAuth
• Google PubSub

Updating .env file: secrets

Create your own .env file from the example supplied:

cp apps/web/.env.example apps/web/.env
cd apps/web
pnpm install

Set the environment variables in the newly created .env. You can see a list of required variables in: apps/web/env.ts.

The required environment variables:

• AUTH_SECRET -- can be any random string (try using openssl rand -hex 32 for a quick secure random string)

• EMAIL_ENCRYPT_SECRET -- Secret key for encrypting OAuth tokens (try using openssl rand -hex 32 for a secure key)

• EMAIL_ENCRYPT_SALT -- Salt for encrypting OAuth tokens (try using openssl rand -hex 16 for a secure salt)

• NEXT_PUBLIC_BASE_URL -- The URL where your app is hosted (e.g., http://localhost:3000 for local development or https://yourdomain.com for production).

• INTERNAL_API_KEY -- A secret key for internal API calls (try using openssl rand -hex 32 for a secure key)

• UPSTASH_REDIS_URL -- Redis URL from Upstash. (can be empty if you are using Docker Compose)

• UPSTASH_REDIS_TOKEN -- Redis token from Upstash. (or specify your own random string if you are using Docker Compose)

• NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS -- Set to true (default) to bypass all premium checks for self-hosting.

Updating .env file with Google OAuth credentials:

• GOOGLE_CLIENT_ID -- Google OAuth client ID. More info here
• GOOGLE_CLIENT_SECRET -- Google OAuth client secret. More info here

Go to Google Cloud. Create a new project if necessary.

Create new credentials:

1. If the banner shows up, configure consent screen (if not, you can do this later)

   1. Click the banner, then Click Get Started.
   2. Choose a name for your app, and enter your email.
   3. In Audience, choose External
   4. Enter your contact information
   5. Agree to the User Data policy and then click Create.
   6. Return to APIs and Services using the left sidebar.

2. Create new credentials:

   1. Click the +Create Credentials button. Choose OAuth Client ID.
   2. In Application Type, Choose Web application
   3. Choose a name for your web client
   4. In Authorized JavaScript origins, add a URI and enter http://localhost:3000 (or your custom domain)
   5. In Authorized redirect URIs enter (or your custom domain):
   • http://localhost:3000/api/auth/callback/google
   • http://localhost:3000/api/google/linking/callback
   6. Click Create.
   7. A popup will show up with the new credentials, including the Client ID and secret.

3. Update .env file:

   1. Copy the Client ID to GOOGLE_CLIENT_ID
   2. Copy the Client secret to GOOGLE_CLIENT_SECRET

4. Update scopes

   1. Go to Data Access in the left sidebar (or click link above)
   2. Click Add or remove scopes
   3. Copy paste the below into the Manually add scopes box:

   https://www.googleapis.com/auth/userinfo.profile
   https://www.googleapis.com/auth/userinfo.email
   https://www.googleapis.com/auth/gmail.modify
   https://www.googleapis.com/auth/gmail.settings.basic
   https://www.googleapis.com/auth/contacts
   

   4. Click Update
   5. Click Save in the Data Access page.

5. Add yourself as a test user

   1. Go to Audience
   2. In the Test users section, click +Add users
   3. Enter your email and press Save

6. Enable Google People API in Google Cloud Console

Updating .env file with Microsoft OAuth credentials:

• MICROSOFT_CLIENT_ID -- Microsoft OAuth client ID
• MICROSOFT_CLIENT_SECRET -- Microsoft OAuth client secret

Go to Microsoft Azure Portal. Create a new Azure Active Directory app registration:

1. Navigate to Azure Active Directory

2. Go to "App registrations" in the left sidebar or search it in the searchbar

3. Click "New registration"

   1. Choose a name for your application
   2. Under "Supported account types" select "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"
   3. Set the Redirect URI:
      • Platform: Web
      • URL: http://localhost:3000/api/auth/callback/microsoft
   4. Click "Register"
   5. In the "Manage" menu click "Authentication (Preview)"
   6. Add the Redirect URI: http://localhost:3000/api/outlook/linking/callback

4. Get your credentials:

   1. The "Application (client) ID" shown is your MICROSOFT_CLIENT_ID
   2. To get your client secret:
      • Click "Certificates & secrets" in the left sidebar
      • Click "New client secret"
      • Add a description and choose an expiry
      • Click "Add"
      • Copy the secret Value (not the ID) - this is your MICROSOFT_CLIENT_SECRET

5. Configure API permissions:

   1. In the "Manage" menu click "API permissions" in the left sidebar

   2. Click "Add a permission"

   3. Select "Microsoft Graph"

   4. Select "Delegated permissions"

   5. Add the following permissions:

      • openid
      • profile
      • email
      • User.Read
      • offline_access
      • Mail.ReadWrite
      • Mail.Send (only required if NEXT_PUBLIC_EMAIL_SEND_ENABLED=true, which is the default)
      • MailboxSettings.ReadWrite

   6. Click "Add permissions"

   7. Click "Grant admin consent" if you're an admin

6. Update your .env file with the credentials:

   MICROSOFT_CLIENT_ID=your_client_id_here
   MICROSOFT_CLIENT_SECRET=your_client_secret_here
   

Updating .env file with LLM parameters

You need to set an LLM, but you can use a local one too:

• Anthropic
• OpenAI
• AWS Bedrock Anthropic
• Google Gemini
• Groq Llama 3.3 70B
• Ollama (local)

For the LLM, you can use Anthropic, OpenAI, or Anthropic on AWS Bedrock. You can also use Ollama by setting the following enviroment variables:

OLLAMA_BASE_URL=http://localhost:11434/api
NEXT_PUBLIC_OLLAMA_MODEL=phi3

Note: If you need to access Ollama hosted locally and the application is running on Docker setup, you can use http://host.docker.internal:11434/api as the base URL. You might also need to set OLLAMA_HOST to 0.0.0.0 in the Ollama configuration file.

You can select the model you wish to use in the app on the /settings page of the app.

If you are using local ollama, you can set it to be default:

DEFAULT_LLM_PROVIDER=ollama

If this is the case you must also set the ECONOMY_LLM_PROVIDER environment variable.

Local Development Infrastructure

We use Postgres for the database and Redis for caching.

The easiest way to run these services locally is using the development Docker Compose file:

# Start Postgres and Redis in the background
docker compose -f docker-compose.dev.yml up -d

Alternatively, you can use remote services like Upstash Redis or Neon Postgres.

Note: This is for local development (using pnpm dev). For production deployment, see Self-Hosting with Docker.

Running the app

To run the migrations:

pnpm prisma migrate dev

To run the app locally for development (slower, but with HMR):

pnpm run dev

Or from the project root:

turbo dev

Production Build with Docker

To build and run the full stack (App + DB + Redis) locally in production mode using Docker:

# Build and start all services (includes Postgres and Redis)
NEXT_PUBLIC_BASE_URL=http://localhost:3000 docker compose --profile all up --build

For production deployments with external databases, see the Docker Self-Hosting Guide.

To run without Docker (local production build):

pnpm run build
pnpm start

Open http://localhost:3000 to view the app in your browser.

Premium

Many features are available only to premium users. To upgrade yourself, make yourself an admin in the .env: ADMINS=hello@gmail.com Then upgrade yourself at: http://localhost:3000/admin.

Set up push notifications via Google PubSub to handle emails in real time

Follow instructions here.

1. Create a topic
2. Create a subscription
3. Grant publish rights on your topic

Set env var GOOGLE_PUBSUB_TOPIC_NAME. When creating the subscription select Push and the url should look something like: https://www.getinboxzero.com/api/google/webhook?token=TOKEN or https://abc.ngrok-free.app/api/google/webhook?token=TOKEN where the domain is your domain. Set GOOGLE_PUBSUB_VERIFICATION_TOKEN in your .env file to be the value of TOKEN.

To run in development ngrok can be helpful:

ngrok http 3000
# or with an ngrok domain to keep your endpoint stable (set `XYZ`):
ngrok http --domain=XYZ.ngrok-free.app 3000

And then update the webhook endpoint in the Google PubSub subscriptions dashboard.

To start watching emails visit: /api/watch/all

Watching for email updates

Set a cron job to run these: The Google watch is necessary. Others are optional.

  "crons": [
    {
      "path": "/api/watch/all",
      "schedule": "0 1 * * *"
    },
    {
      "path": "/api/resend/summary/all",
      "schedule": "0 16 * * 1"
    },
    {
      "path": "/api/reply-tracker/disable-unused-auto-draft",
      "schedule": "0 3 * * *"
    }
  ]

Here are some easy ways to run cron jobs. Upstash is a free, easy option. I could never get the Vercel vercel.json. Open to PRs if you find a fix for that.

Advanced Docker Usage

For detailed instructions on:

• Building custom Docker images
• Using external databases (RDS, Neon, Upstash)
• AWS EC2 deployment with ALB
• Production configuration

See our comprehensive guides:

• Docker Self-Hosting Guide
• AWS EC2 Deployment Guide

Calendar integrations

Google Calendar

1. Visit: https://console.cloud.google.com/apis/library
2. Search for "Google Calendar API"
3. Click on it and then click "Enable"
4. Visit: credentials:
   1. Click on your project
   2. In Authorized redirect URIs add:
   • http://localhost:3000/api/google/calendar/callback

Microsoft Calendar

1. Go to your existing Microsoft Azure app registration (created earlier in the Microsoft OAuth setup)
2. Add the calendar redirect URI:
   1. In the "Manage" menu click "Authentication (Preview)"
   2. Add the Redirect URI: http://localhost:3000/api/outlook/calendar/callback
3. Add calendar permissions:
   1. In the "Manage" menu click "API permissions"
   2. Click "Add a permission"
   3. Select "Microsoft Graph"
   4. Select "Delegated permissions"
   5. Add the following calendar permissions:
      • Calendars.Read
      • Calendars.ReadWrite
   6. Click "Add permissions"
   7. Click "Grant admin consent" if you're an admin

Note: The calendar integration uses a separate OAuth flow from the main email OAuth, so users can connect their calendar independently.

Contributing to the project

You can view open tasks in our GitHub Issues. Join our Discord to discuss tasks and check what's being worked on.

ARCHITECTURE.md explains the architecture of the project (LLM generated).