Ripple

Know who opened your email, how often, and when. Open and click tracking for Gmail outreach.

Overview

Cold outreach from Gmail is a black box: you send, then wait. Ripple adds a tracking pixel and tracked links to each email, so you see opens, repeat opens and clicks per recipient. It was built for speaker and sponsor outreach at E-Summit, IIT Roorkee, and works for anyone sending personal outreach at small scale. It is honest about limits: proxy fetches, prefetches and your own views are flagged or filtered, not counted as reads.

Demo

Live: https://ripplemail.vercel.app

Features

• Campaigns: import contacts from CSV, write a template with merge fields ({{first_name}}, {{org}}, …), schedule, and send from your own Gmail account. Per-account daily limit (default 25).
• Chrome extension: track emails you send from Gmail's own compose window. Read ticks in the Sent folder.
• Per-recipient tracking: unique pixel and link tokens per recipient. Opens, reopens, clicks, first/last open.
• Analytics: open and click rates, hour × weekday heatmap, follow-up lists (not opened, opened often, clicked), CSV and printable reports.
• Replies inbox: replies pulled from Gmail into a shared inbox. Admins see the whole team; answers sent from Ripple are tracked too.
• Teams: workspaces with email invites and admin/member roles.
• MCP connector: use Ripple from Claude, ChatGPT and other AI apps. Tools read campaigns, contacts and replies and create drafts. They never send.

Getting Started

Prerequisites

Tool	Version	Notes
Bun	1.3+	Package manager and test runner
Postgres	Any recent	Built against Supabase; any Postgres works with the pg adapter
Google Cloud project	n/a	OAuth client with the Gmail API enabled
Vercel Blob store	n/a	Only needed for attachments

Installation

git clone https://github.com/thedevkansal/ripple.git

cd ripple

bun install

cp apps/web/.env.example apps/web/.env

Fill in apps/web/.env (see Configuration), then create the database tables:

cd apps/web && bunx prisma migrate deploy

Start the dev server on http://localhost:3000:

bun run dev

Configuration

All variables live in apps/web/.env.

Name	Description	Example
DATABASE_URL	Postgres connection string (Supabase transaction pooler, port 6543)	postgresql://postgres.<REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres
DIRECT_URL	Optional. Session connection for migrations (Supabase session pooler, port 5432). Defaults to DATABASE_URL	postgresql://postgres.<REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:5432/postgres
APP_URL	Public origin. Used in tracking pixels, links and OAuth redirects	http://localhost:3000
AUTH_SECRET	Auth.js session secret	output of openssl rand -base64 32
AUTH_GOOGLE_ID	Google OAuth client ID	<CLIENT_ID>.apps.googleusercontent.com
AUTH_GOOGLE_SECRET	Google OAuth client secret	<YOUR_CLIENT_SECRET>
TOKEN_ENCRYPTION_KEY	32-byte base64 key that encrypts Gmail refresh tokens	output of openssl rand -base64 32
CRON_SECRET	Bearer secret for the send-queue endpoint	output of openssl rand -hex 32
BLOB_READ_WRITE_TOKEN	Vercel Blob token for attachments	vercel_blob_rw_<YOUR_TOKEN>

Google OAuth setup

1. Enable the Gmail API in your Google Cloud project.
2. Create an OAuth client (Web application) and add these redirect URIs:
   • <APP_URL>/api/auth/callback/google (sign-in)
   • <APP_URL>/api/gmail/callback (Gmail connect)
3. Add gmail.send and gmail.readonly scopes to the consent screen. While the app is in Testing mode, add each user as a test user.

Usage

Common commands

Run from the repo root.

Command	What it does
bun run dev	Start the web app in dev mode
bun run build	Production build of the web app
bun run test	Run all workspace tests
bun run lint	Lint the web app
bun run db:generate	Regenerate the Prisma client
bun run build:extension	Build the Chrome extension into apps/extension/dist

Send queued emails

Scheduled campaigns go into a queue. Something must call the queue endpoint every minute; it then also syncs replies.

curl -X POST "http://localhost:3000/api/cron/send" -H "Authorization: Bearer <CRON_SECRET>"

Expected output (counts vary; replies holds the reply-sync result):

{"sent":0,"failed":0,"deferred":0,"replies":{}}

In production an external scheduler such as cron-job.org calls it. .github/workflows/send-queue.yml is a backup that runs every 5 minutes once the RIPPLE_URL and CRON_SECRET repo secrets are set.

Chrome extension

bun run --filter @ripple/extension build:dev

Then open chrome://extensions, turn on Developer mode, click Load unpacked and pick apps/extension/dist. Details in apps/extension/README.md.

MCP connector

Add <APP_URL>/api/mcp as a custom connector in your AI app. Ripple runs its own OAuth server, so the app asks you to sign in and approve. Exact steps per app are on the dashboard's Settings page.

Project Structure

ripple/
├── apps/
│   ├── web/                      Next.js app: landing page, dashboard, API
│   │   ├── prisma/               Schema and SQL migrations
│   │   └── src/
│   │       ├── app/
│   │       │   ├── dashboard/    Campaigns, contacts, templates, replies, settings
│   │       │   ├── t/            Tracking endpoints: pixel (o) and click redirect (c)
│   │       │   └── api/          Auth, Gmail connect, cron, extension, MCP, OAuth
│   │       ├── components/       UI components by area
│   │       └── lib/              Sending, queue, tracking, analytics, Gmail, MCP tools
│   └── extension/                Chrome MV3 extension for Gmail compose
├── packages/
│   └── shared/                   Event classification, templating, link instrumentation
├── docs/PLAN.md                  Design notes and tracking model
└── .github/workflows/            CI and send-queue backup cron

Tech Stack

• Language: TypeScript
• Web: Next.js 16 (App Router), React 19, Tailwind CSS 4, Motion
• Data: Prisma 7, Supabase Postgres, Vercel Blob
• Auth: Auth.js v5 with Google; Gmail API for sending and reading replies
• AI: Model Context Protocol server (mcp-handler)
• Tooling: Bun workspaces, Bun test, ESLint, GitHub Actions
• Hosting: Vercel

Known Issues

• Gmail image proxy: Gmail fetches the pixel through its proxy, so IP and device are hidden. Open timing still works.
• Apple Mail Privacy Protection prefetches images. These are flagged as prefetches, not opens.
• Image blocking: Outlook and many corporate clients block images. Unopened does not mean unread.
• Google verification: gmail.readonly is a restricted scope. A public launch needs Google's security assessment; until then the OAuth app stays in Testing mode (100 test users max).

Contributing

1. Fork the repo and create a branch from main.

2. Set up as in Getting Started.

3. For schema changes, edit apps/web/prisma/schema.prisma and add a migration:

   cd apps/web && bun run db:migrate
   

4. Run the same checks as CI before pushing:

   bun run test
   

   bun run lint
   

   cd apps/web && bunx next typegen && bunx tsc --noEmit
   

   cd apps/extension && bunx tsc --noEmit
   

5. Open a pull request against main. CI must pass.

License

No license yet. All rights reserved until one is added.

Acknowledgements / Contact

Built by Dev Kansal for E-Summit, IIT Roorkee.

Questions and bugs: open an issue.