Inbox Zero

What is Inbox Zero about?

Inbox Zero is an AI‑powered personal assistant that helps you manage your email faster. It automatically categorizes senders, suggests replies in your own style, tracks messages that need a response, and offers analytics on your email habits.

How to use Inbox Zero?

1. Deploy – Deploy the app via Vercel, Docker, or locally with pnpm/Turbo.
2. Configure – Set required environment variables (OAuth credentials, database URL, Redis, LLM provider, etc.) in the .env file.
3. Connect your mailbox – Authorize Google or Microsoft accounts to grant the app access to Gmail/Outlook.
4. Interact – Use the web UI to view AI‑generated draft replies, set cursor rules in plain English, unsubscribe or block bulk emails, and monitor reply‑tracking status.
5. Customize – Choose your LLM (OpenAI, Anthropic, Ollama, etc.) on the Settings page and tweak premium features if needed.

Key Features of Inbox Zero

• AI Personal Assistant – Generates draft replies in your tone and organizes conversations.
• Cursor Rules – Write plain‑english rules that dictate how the AI should handle incoming mail.
• Reply Zero Tracker – Shows which emails you still need to answer and which are awaiting replies.
• Smart Categories – Automatic sender classification.
• Bulk Unsubscriber – One‑click unsubscribe and archive of never‑read newsletters.
• Cold Email Blocker – Filters and blocks unsolicited cold outreach.
• Email Analytics – Visualizes response times, email volume trends, and productivity metrics.
• Multi‑Provider OAuth – Supports Google and Microsoft accounts.
• Flexible LLM Integration – Works with OpenAI, Anthropic, Bedrock, Gemini, Groq, Ollama, etc.
• Docker & Vercel Support – Easy deployment options.

Use Cases

• Busy Professionals – Reduce time spent reading and replying to emails.
• Sales Teams – Quickly draft personalized outreach replies and block cold spam.
• Customer Support – Auto‑draft responses and track pending tickets via email.
• Developers – Self‑host to integrate with internal tools or CI pipelines.
• Privacy‑Conscious Users – Run the app on personal infrastructure, controlling all data.

FAQ

Q: Do I need to pay for any services? A: The core app is open source and free. Premium features require a paid subscription or making yourself an admin in the .env file.

Q: Which email providers are supported? A: Google Gmail (via OAuth) and Microsoft Outlook/Exchange are supported.

Q: Can I run the app locally without Docker? A: Yes. After cloning the repo, run pnpm install, configure .env, and start with turbo dev or pnpm run dev.

Q: What LLMs can I use? A: OpenAI, Anthropic, AWS Bedrock (Anthropic), Google Gemini, Groq, and local Ollama models are supported. Set the appropriate env vars.

Q: How do I receive real‑time email notifications? A: Set up Google Pub/Sub, create a topic and subscription, and configure GOOGLE_PUBSUB_TOPIC_NAME and GOOGLE_PUBSUB_VERIFICATION_TOKEN in .env. The app provides a webhook endpoint for push notifications.

Q: Is there a Docker image available? A: Yes. Build with docker build --build-arg NEXT_PUBLIC_BASE_URL="https://your-domain.com" -t inbox-zero -f docker/Dockerfile.prod . and run with the required environment variables.

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

AI Assistant	Reply Zero
Gmail client	Bulk Unsubscriber

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 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 PostgreSQL and Redis:

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

2. Install dependencies and set up environment:

   pnpm install
   ./docker/scripts/setup-env.sh  # Creates .env with auto-generated secrets
   

3. Configure OAuth and LLM:

   Edit apps/web/.env and add:

   • OAuth credentials (at least one required): Google OAuth or Microsoft OAuth
   • LLM provider: Uncomment one provider block and add your API key

4. Run database migrations:

   cd apps/web
   pnpm prisma migrate dev
   

5. Run the development server:

   pnpm dev
   

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

The setup script auto-generates all required secrets. The sections below cover the services you need to configure manually. For a comprehensive reference of all environment variables, see the Environment Variables Guide.

Google OAuth Setup

Go to Google Cloud Console and 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
   • http://localhost:3000/api/google/calendar/callback (only required for calendar integration)
   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
   https://www.googleapis.com/auth/calendar (only required for calendar integration)
   

   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 required APIs in Google Cloud Console:

   • Google People API (required)
   • Google Calendar API (only required for calendar integration)

Google PubSub Setup

PubSub enables real-time email notifications. Follow the official guide:

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

Set GOOGLE_PUBSUB_TOPIC_NAME in your .env file.

When creating the subscription, select Push and set the URL to: https://yourdomain.com/api/google/webhook?token=TOKEN

Set GOOGLE_PUBSUB_VERIFICATION_TOKEN in your .env file to the value of TOKEN.

For local development, use ngrok to expose your local server:

ngrok http 3000

Then update the webhook endpoint in the Google PubSub subscriptions dashboard.

Email watch renewal: Gmail watch subscriptions expire periodically and must be renewed. If using Docker Compose, this is handled automatically by the cron container every 6 hours. Otherwise, set up a cron job to call /api/watch/all (see Self-Hosting Guide).

Microsoft OAuth Setup

Go to Microsoft Azure Portal and 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 following Redirect URIs:
      • http://localhost:3000/api/outlook/linking/callback
      • http://localhost:3000/api/outlook/calendar/callback (only required for calendar integration)

4. Get your credentials from the Overview tab:

   1. Copy the "Application (client) ID" → this is your MICROSOFT_CLIENT_ID
   2. Go to "Certificates & secrets" in the left sidebar
      • Click "New client secret"
      • Add a description and choose an expiry
      • Click "Add"
      • Copy the Value → this is your MICROSOFT_CLIENT_SECRET (Important: copy Value, not Secret ID)

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
      • Calendars.Read (only required for calendar integration)
      • Calendars.ReadWrite (only required for calendar integration)

   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
   

LLM Setup

In your .env file, uncomment one of the LLM provider blocks and add your API key:

• Anthropic
• OpenAI
• Google Gemini
• OpenRouter
• Vercel AI Gateway
• AWS Bedrock
• Groq

Users can also change the model in the app on the /settings page.

Local Production Build

To test a production build locally:

# Without Docker
pnpm run build
pnpm start

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

Self-Hosting

For production deployments, see our guides:

• Self-Hosting Guide
• AWS EC2 Deployment
• AWS Copilot (ECS/Fargate)

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).