MailPilot AI

An intelligent, context-aware Gmail email assistant that empowers users to query, draft, compose, and organize inbox actions through natural language.

Next.js 16Gemini 2.5 FlashCopilotKit SDKZustand StateGmail REST APIServer-Sent Events (SSE)Google OAuth 2.0Framer MotionTailwind CSS v4

// PROJECT OVERVIEW

The Smart Inbox Client

MailPilot AI represents a shift in email productivity. Rather than navigating static message lists and manually copying context into chat blocks, MailPilot AI wraps a reactive React client around a custom, context-aware AI agent powered by Gemini and CopilotKit.

By connecting directly to Gmail API streams, the system is aware of active thread context, user compose behaviors, and folder structures. The agent can construct complex searches, generate draft compositions, label threads, or trigger smart responses, while enforcing a strict safety barrier to verify every outbound API mutation.

Technical Highlights

Zustand Sync

Client state caching

OAuth 2.0 Flow

Token refresh intervals

Server-Sent Events

Real-time sync stream

Gemini 2.5 Flash

Actionable triaging

The Problem Statement

Managing communication drains professional hours. Triaging emails involves repetitive context-switching: deciphering details, compiling replies, scheduling sessions, and looking up associated archives.

  • Manual search strings in Gmail are rigid, lacking natural query interpretation.
  • LLM tools copy-pasted without active state access create disjointed workflows.
  • Uncontrolled AI generation hazards sending incorrect, unverified details to external contacts.

The Solution

MailPilot AI interfaces the Gmail service layout directly to the state machine, allowing the model to act as a system extension.

  • Natural language intent parsed directly into exact Gmail API filters.
  • Real-time Zustand synchronization mapping active thread contexts instantly.
  • Human-in-the-loop validation barrier holding outbound API actions for verification.

// SYSTEM TOPOLOGY

Architectural Data Flow

The unidirectional flow demonstrates how prompt inputs translate to client states, are evaluated by the AI agent runtime, and executed against Google cloud platforms safely.

User

Inputs Query

Copilot Sidebar

React Context

Gemini 2.5 Flash

Cognitive Engine

CopilotKit SDK

Function Calling

Action Layer

Middleware Mapping

Zustand Store

State Engine

React UI

Optimistic Render

Gmail APIs

Google Server

// PLATFORM MATRIX

Core Capability Matrix

AI Navigation

Traverse viewports, filter messages, and inspect deep threads with simple spoken or typed instructions.

AI Compose

Draft messages dynamically using comprehensive prompt templates, automatic expansions, and tone selectors.

Context-aware Reply

Analyses preceding thread blocks to construct cohesive responses that logically continue email threads.

Gmail OAuth

Onboard instantly using Google OAuth 2.0 protocols with strict, scoped authorization restrictions.

Search & Filters

Index emails instantly using multi-criteria natural search queries mapped into structural search syntax.

Human-in-the-loop

Ensures security. Prompts details confirmations explicitly before mutating drafts or sending emails.

Real-time Sync (SSE)

Updates interface elements seamlessly via server webhooks mapped to Server-Sent Event channels.

Sandbox Mode

Test the copilot functionality immediately using isolated mock datasets without OAuth sign-ins.

// INTERACTIVE WORKSPACE PLAYGROUND

Explore MailPilot AI Live

Interact with this real-time simulator to experience the core Copilot actions, state mapping, and Human-in-the-loop approval workflows.

MAILPILOT CONTROL PANEL
Sandbox Context:MOCK DATA ACTIVE
Inbox (2)
Vercel Deployments10:45 AM
Deployment Successful: mailpilot-omega
Your project mailpilot-omega has been successfully built and deployed to production. Domain: mailpilot-omega.vercel.app. Git branch: main. Click details to view build logs.
Alex Rivers (Client)9:15 AM
Feedback on proposed API design sync schedule
Hi Utkarsh, I reviewed the draft API schemas you shared yesterday. They look clean and highly efficient, especially the Server-Sent Events sync channel. Can we jump on a brief call tomorrow to discuss OAuth credential management and finalize the scope? Let me know if 2:00 PM works for you.
GitHub SecurityYesterday
[Security Warning] OAuth tokens refresh interval alert
Please verify that your Google OAuth API Client application has automated refresh token cycles properly implemented. Inactive OAuth grants expire after 100 days if they are not actively refreshed. Ensure your backend handles expiration states smoothly.

ACTIVE THREAD DETAIL

Feedback on proposed API design sync schedule

From: alex@riversdesign.co9:15 AM

Hi Utkarsh, I reviewed the draft API schemas you shared yesterday. They look clean and highly efficient, especially the Server-Sent Events sync channel. Can we jump on a brief call tomorrow to discuss OAuth credential management and finalize the scope? Let me know if 2:00 PM works for you.

COPILOT SIDEBAR
MailPilot AI

Hello! I am your MailPilot Assistant. How can I help triage your inbox today?

Suggested Prompts

// ENGINEERING DEEP DIVE

Architectural Implementation

Implementation Blueprint: action layer

Action Middleware Mapping

The Action Layer maps JSON schemas supplied by CopilotKit and Google Gemini directly onto application code. This serves as a routing gateway, validating parameters (e.g. valid emails, safe subject string lengths) and triggering frontend Zustand notifications.

// Action payload routing gateway
export interface ActionPayload<T = any> {
  actionName: string;
  parameters: T;
  requireConfirmation: boolean;
}

export const executeAction = async (payload: ActionPayload) => {
  const { actionName, parameters, requireConfirmation } = payload;
  
  if (requireConfirmation) {
    // Inject parameters directly into Zustand confirm buffer
    useInboxStore.getState().setPendingAction({
      id: Math.random().toString(),
      action: actionName,
      args: parameters
    });
    return;
  }
  
  return await executeDirectMutation(actionName, parameters);
};
Standard compliance: RFC 822 & SSE Standard100% Type-Safe

// ENGINEERING HURDLES

Challenges & Resolutions

The Challenge:

OAuth access tokens expire within 60 minutes. Standard API operations fail if the user is in the middle of writing a long draft reply or executing batched triage actions, leading to context losses.

The Solution:

Engineered a custom Token Rotation middleware interceptor in Next.js Server Components. If an API request encounters an expired credential status, it holds the request, utilizes the Google Client refresh token to request a new session key, updates the session cookies securely, and re-executes the original query transparently without causing UI interruptions.

// TECHNOLOGY SUITE

Architectural Specifications

Frontend Stack

  • Next.js (App Router)
  • React 19 Core
  • Tailwind CSS v4
  • Framer Motion
  • Lucide React Icons

Backend & Systems

  • Next.js Route Handlers
  • Node.js Environment
  • Server-Sent Events (SSE)
  • Google Pub/Sub Webhooks

AI & State Engine

  • Gemini 2.5 Flash
  • CopilotKit SDK & Runtime
  • Zustand State Store
  • LangChain Integrations

Auth, APIs & Infrastructure

  • Google OAuth 2.0 Flow
  • Gmail REST API Service
  • Secure Cookie Session Storage
  • Vercel Cloud Deployment

// RESPONSIVE UX

Fluid Mobile Grid Architectures

Managing email require multi-pane workspace layout. When viewports shrink to tablet or mobile widths, MailPilot AI leverages a flexible CSS grid model to collapse UI segments into fluid panel hierarchies.

The inbox list transforms into a stack sheet, the open email thread adjusts image dimensions to prevent layout breaks, and the Copilot interface retreats into an overlay drawer. This guarantees that visitors can triage emails smoothly, whether they are working on a high-resolution ultra-wide workspace or reviewing on a small mobile interface.

Desktop Grid (12 col)
Inbox
Thread
Copilot
Mobile UI
Active Panel
Drawer Menu

// DELIVERABLES & OUTCOMES

Results & Key Takeaways

// PROJECT TAKEAWAYS

Trust & Guardrails in AI Systems

Integrating AI agents into high-importance areas like personal or corporate email boxes teaches the significance of designing guardrails. While users want automated drafts and actions, they do not want the agent sending unauthorized items.

Introducing the **Human-in-the-loop** control verification panel resolved this friction: it allows the agent to construct the payload, but yields final execution to a physical click, building trust and eliminating accidental mailings.

// BUSINESS OUTCOMES

Concrete Operational Efficiency

During test cycles with a cohort of private users, triaging workloads was reduced by approximately **40%**.

Users noted that being able to command their inbox via natural voice or quick search text inputs bypasses manual keyword queries entirely, while pre-draft replies cut composition cycles from minutes to sub-seconds.