Auto-inbox

Auto-inbox is an open-source AI inbox assistant for teams that want faster customer replies without giving up human review. It reads like a premium support dashboard: incoming emails, intent detection, FAQ context, a generated reply, activity logs, and a clear manual Enviar action before anything is sent.

Overview

Auto-inbox turns the workflow of an AI email responder into a product-ready interface. The browser build still uses realistic demo data so anyone can explore the experience without credentials, while the Electron desktop build can connect Gmail, Google Sheets, and a configurable AI provider for a local MVP flow.

The product direction is intentionally human-in-the-loop: AI prepares the response, but the user reviews and sends it manually.

Highlights

• Premium 4-column inbox dashboard inspired by modern email and support tools.
• Dark sidebar with mailbox, automation, integration, and mode controls.
• Searchable inbox list with unread states and selected-message focus.
• Email detail view with customer metadata, intent, confidence, FAQ matches, and history.
• AI suggested reply composer with formatting controls, regenerate action, and manual Enviar button.
• Desktop-ready Gmail OAuth connection panel with sync state, history ID tracking, and least-privilege scopes.
• Configurable Gmail heartbeat for automatic inbox checks and duplicate skipping.
• Google Sheets MVP integration for FAQ rows, automation rules, and activity logs.
• Configurable AI-backed intent detection and draft generation in desktop mode.
• Gmail draft creation for manual review before sending.
• Automation status panel and activity log for observability.
• English and Spanish interface language toggle while keeping email content untouched.
• Real light/dark theme selector using CSS theme tokens and native color-scheme rendering.
• Responsive layout with no horizontal overflow on mobile.

Tech Stack

• React 19
• TypeScript
• Vite
• lucide-react
• CSS modules-style global styling with responsive grid layouts

Getting Started

npm install
npm run dev

Open the local URL printed by Vite.

Desktop Development

Auto-inbox now includes an Electron shell for the future .exe build. In desktop mode, the React app receives a secure window.autoInboxGmail bridge from Electron instead of handling Google tokens directly.

npm run dev:desktop

For a Windows installer build:

npm run dist:desktop

Build

npm run build

Gmail OAuth Architecture

Auto-inbox is prepared for the safest desktop path: Google OAuth 2.0 for installed apps, Gmail API scopes, and secure token storage in the desktop shell.

• The React UI calls a window.autoInboxGmail bridge when Tauri or Electron exposes it.
• The Electron preload exposes that bridge through isolated IPC.
• The browser build falls back to a demo bridge so the open-source app remains easy to run.
• The first production scopes are gmail.readonly and gmail.compose, avoiding full mailbox access unless the product truly needs it.
• Initial sync can use users.messages.list and users.messages.get.
• Incremental sync can persist the latest historyId and call users.history.list.
• The UI includes a configurable heartbeat, currently 30 seconds to 15 minutes, so users choose how often Gmail is checked.
• Auto-sync keeps a local seenMessageIds cache and skips duplicate message IDs before counting or processing new emails.
• Sending should stay human-in-the-loop: generate a Gmail draft first, then let the user review and send.
• Access and refresh tokens are encrypted with Electron safeStorage and kept outside frontend storage.

To test real Gmail OAuth locally, create a Google Cloud OAuth client for a desktop app and set:

GOOGLE_OAUTH_CLIENT_ID=your-client-id
GOOGLE_OAUTH_CLIENT_SECRET=optional-client-secret
AI_PROVIDER=openai
AI_API_KEY=your-provider-api-key
AI_MODEL=gpt-5-mini

The app also reads a local .env file during desktop startup. The web-only Vite build still works without Gmail credentials.

AI Provider Configuration

In desktop mode, the Electron process calls the selected AI provider so API keys are not stored in the React frontend. Auto-inbox sends the selected email body plus the active FAQ and Rules rows, asks for JSON, and writes the returned intent, confidence, FAQ matches, activity items, and suggested reply back into the inbox UI.

Set AI_PROVIDER to one of:

openai
deepseek
anthropic
moonshot
custom-openai-compatible

Recommended examples:

# OpenAI
AI_PROVIDER=openai
AI_API_KEY=your-openai-api-key
AI_MODEL=gpt-5-mini

# DeepSeek
AI_PROVIDER=deepseek
AI_API_KEY=your-deepseek-api-key
AI_MODEL=deepseek-v4-flash

# Claude / Anthropic
AI_PROVIDER=anthropic
AI_API_KEY=your-anthropic-api-key
AI_MODEL=claude-sonnet-4-6

# Kimi / Moonshot
AI_PROVIDER=moonshot
AI_API_KEY=your-moonshot-api-key
AI_MODEL=kimi-k2.6

# Any OpenAI-compatible local or hosted server
AI_PROVIDER=custom-openai-compatible
AI_API_KEY=your-api-key
AI_MODEL=your-model
AI_BASE_URL=http://127.0.0.1:1234/v1

Provider-specific variables also work, such as OPENAI_API_KEY, DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, and MOONSHOT_API_KEY. If no key is configured, the app keeps running with the demo AI bridge.

Provider defaults:

Provider	Protocol	Default base URL	Default model	API key env
openai	Responses API with JSON schema	https://api.openai.com/v1	gpt-5-mini	AI_API_KEY or OPENAI_API_KEY
deepseek	OpenAI-compatible Chat Completions with JSON mode	https://api.deepseek.com	deepseek-v4-flash	AI_API_KEY or DEEPSEEK_API_KEY
anthropic	Claude Messages API with output_config.format	https://api.anthropic.com	claude-sonnet-4-6	AI_API_KEY or ANTHROPIC_API_KEY
moonshot	OpenAI-compatible Chat Completions with JSON mode	https://api.moonshot.ai/v1	kimi-k2.6	AI_API_KEY or MOONSHOT_API_KEY
custom-openai-compatible	OpenAI-compatible Chat Completions	http://127.0.0.1:1234/v1	custom-model	AI_API_KEY

For custom OpenAI-compatible servers, set AI_BASE_URL to the server's /v1 base URL. Auto-inbox appends /chat/completions unless the value already ends with that path. AI_JSON_MODE=true sends response_format: {"type":"json_object"}; it defaults to true for DeepSeek and Kimi/Moonshot, and false for custom servers because local gateways vary.

Reference docs:

• OpenAI models and Responses API: https://platform.openai.com/docs/models
• DeepSeek quick start and JSON output: https://api-docs.deepseek.com/
• Claude Messages API and structured outputs: https://platform.claude.com/docs/en/api/overview
• Kimi/Moonshot API overview and JSON mode: https://platform.kimi.ai/docs/api/overview

Google Sheets MVP

The first Sheets integration is intentionally simple: paste a Google Sheet URL or spreadsheet ID inside the app. Auto-inbox expects these tabs:

FAQ
  enabled | intent | question | answer | tags | source | updated_at

Rules
  enabled | priority | match_text | intent | action | notes

Activity
  timestamp | email_id | sender | subject | intent | confidence | status | draft_created

Settings
  key | value

In desktop mode, the Electron bridge requests the https://www.googleapis.com/auth/spreadsheets scope, validates the selected spreadsheet, reads FAQ and Rules, and appends rows to Activity. In browser mode, the same UI uses demo data so contributors can work without Google credentials.

Automation Engine

The inbox sync logic is separated from the React UI under src/automation. The current engine owns Gmail sync execution, heartbeat scheduling helpers, local heartbeat persistence, duplicate detection through a bounded seenMessageIds cache, and returns newly loaded Gmail messages so the UI can classify and draft replies.

Product Roadmap

• Settings UI for Gmail OAuth client configuration.
• Google Picker support for choosing a spreadsheet without pasting an ID.
• Safety rules for newsletters, billing, legal, and sensitive support cases.
• Desktop installer polish, app icon, and signed releases.
• Optional hosted SaaS mode for always-on automation.

Project Structure

Auto-Inbox/
  electron/                Electron shell, preload bridge, and Google OAuth flow
  docs/images/             README and GitHub assets
  src/automation/          Inbox sync engine, scheduler helpers, and dedupe store
  src/gmail/               Gmail OAuth bridge, API helpers, and sync types
  src/sheets/              Sheets API helpers, bridge, and MVP data mappers
  src/main.tsx             Main React application
  src/styles.css           Premium dashboard styling
  .env.example             Future desktop OAuth configuration placeholders
  index.html               Vite entry
  package.json             Scripts and dependencies
  tsconfig.electron.json   Electron TypeScript build config

Philosophy

Auto-inbox is not trying to hide automation behind a black box. It is designed around review, clarity, and trust: show the reasoning context, show the generated reply, and keep the final send action in the user's hands.

License

MIT