Overview
Subs is a production-ready email signup API designed for collecting newsletter subscribers, beta signups, and other email registrations. It stores emails directly in Google Sheets for easy management and includes Cloudflare Turnstile integration for invisible bot protection.
Features
- Google Sheets Storage: Direct integration with Google Sheets - no separate database required. Automatic sheet tab creation and deduplication across tabs.
- Bot Protection: Cloudflare Turnstile integration blocks 99% of spam with zero user friction - no visible CAPTCHAs.
- Multiple Embedding Options: Embed via iframe, inline HTML, direct POST, or JavaScript SDK on any website.
- Extended Metadata: Collect name, source, tags, and custom metadata alongside email addresses.
- Bulk Signups: Process up to 100 signups at once via the bulk API endpoint.
- Production Observability: Built-in Prometheus metrics, structured JSON logging, health checks, and stats endpoints.
Deployment Options
- Bun/Node.js Server: Traditional server deployment with hot reload for development
- Cloudflare Workers: Edge deployment for global low-latency performance
- Docker: Multi-stage Docker builds with Docker Compose support
API Endpoints
| Endpoint | Description |
|---|---|
POST /api/signup | Basic email signup |
POST /api/signup/extended | Signup with name, source, tags |
POST /api/signup/bulk | Bulk signups (up to 100) |
GET /api/stats | Signup statistics |
GET /api/health | Health check |
GET /api/config | Configuration info |
GET /api/metrics | Prometheus metrics |
Technology Stack
- Runtime: Bun
- Framework: ElysiaJS (fast, type-safe web framework)
- Validation: Zod schemas with compile-time and runtime type safety
- Bot Protection: Cloudflare Turnstile
- Storage: Google Sheets API (REST-based, no SDK)
- Auth: Google Service Account with JWT signing via jose
- Monitoring: Prometheus metrics + Pino structured logging
- Testing: Vitest with unit and integration tests
- Deployment: Cloudflare Workers via Wrangler