Qail - AI Cold Email Scorer

Qail is a Chrome extension integrated into Gmail that evaluates cold emails before sending using AI scoring. Get real-time feedback on tone, spam risk, personalization, CTA quality, and simulate likely recipient replies.

Architecture

Monorepo Structure

qail/
├── apps/
│   ├── backend/          # Python FastAPI service
│   └── extension/        # Chrome extension (TypeScript + React)
├── shared/               # Shared schemas and constants
├── docker-compose.yml    # Docker configuration
└── README.md

Quick Start

Prerequisites

• Docker & Docker Compose
• Bun 1.0+ (for extension development)
• Python 3.11+ (for local backend development)
• DeepSeek API key

1. Backend Setup

Using Docker (Recommended):

# Copy environment template
cp .env.example .env

# Edit .env and add your DeepSeek API key
# DEEPSEEK_API_KEY=your_key_here

# Start services
docker-compose up -d

# Check backend health
curl http://localhost:8000/health

Local Development:

cd apps/backend

# Install dependencies
poetry install

# Run migrations
poetry run alembic upgrade head

# Start server
poetry run uvicorn app.main:app --reload

2. Chrome Extension Setup

cd apps/extension

# Install dependencies
bun install

# Build extension
bun run build

# Or watch mode for development
bun run dev

Load in Chrome:

1. Open chrome://extensions/
2. Enable "Developer mode"
3. Click "Load unpacked"
4. Select apps/extension/dist folder

Configure Extension:

1. Click the Qail extension icon
2. Set API URL (default: http://localhost:8000)
3. Save settings

Usage

1. Open Gmail and compose a new email
2. Click the "AI Cold Score" button in the compose toolbar
3. View real-time scoring across 4 dimensions:
   • Tone (25%) - Professional, authentic, respectful
   • Spam Risk (25%) - Spam indicators and red flags
   • Personalization (30%) - Research signals and customization
   • CTA Quality (20%) - Clear, low-friction call-to-action
4. Review suggestions and improve your email

API Endpoints

POST /api/score-email

Analyze email and return composite score (0-100)

Request:

{
  "subject": "Quick question about your marketing automation",
  "body": "Hi John, I noticed...",
  "recipient_context": "Marketing Director at SaaS company"
}

Response:

{
  "composite_score": 78.5,
  "tone": { "score": 85, "weight": 0.25, "feedback": "...", "warnings": [] },
  "spam_risk": { "score": 90, "weight": 0.25, "feedback": "...", "warnings": [] },
  "personalization": { "score": 72, "weight": 0.30, "feedback": "...", "warnings": [] },
  "cta": { "score": 65, "weight": 0.20, "feedback": "...", "warnings": ["..."] },
  "suggestions": ["Add specific reference to recipient's work", "..."]
}

POST /api/simulate-reply

Simulate recipient responses in different modes

Modes: interested, neutral, objection, ignore, skeptical

Development Commands

Backend

cd apps/backend

# Run tests
poetry run pytest

# Run specific test file
poetry run pytest tests/test_scoring.py

# Format code
poetry run black .

# Lint
poetry run ruff check .

# Create migration
poetry run alembic revision --autogenerate -m "description"

# Apply migrations
poetry run alembic upgrade head

Extension

cd apps/extension

# Development build (watch mode)
bun run dev

# Production build
bun run build

# Type checking
bun run type-check

# Lint
bun run lint

Technology Stack

Backend:

• Python 3.11
• FastAPI 0.115.8 (with Starlette security fixes)
• SQLAlchemy 2.0.44
• Pydantic 2.12.0
• PostgreSQL 15
• DeepSeek API for AI scoring

Chrome Extension:

• TypeScript 5.3
• React 18.2
• Vite 5.0 (with @crxjs/vite-plugin)
• InboxSDK 2.2 (Gmail integration)
• Bun 1.0+ (package manager & runtime)

Security Features

• ✅ No Gmail inbox read permissions
• ✅ No email content storage (transient analysis only)
• ✅ HTTPS only
• ✅ Latest security-patched dependencies
• ✅ Strict JSON schema validation

Performance

• Target latency: < 2.5s per email score
• Error rate: < 1%

v1 Scope

Included:

• Real-time email scoring (4 dimensions)
• Reply simulation (5 modes)
• Gmail compose integration
• User-triggered suggestions

Not Included (Future):

• Full deliverability monitoring
• CRM integrations
• Campaign-level analytics
• Automated sending
• Multi-language support (English only in v1)

Contributing

See CLAUDE.md for development guidelines and architecture details.

License

MIT