ProgrammableInbox
A secondary inbox built for developers.
Spin up a programmable email address in seconds. ProgrammableInbox receives, categorizes, and
extracts every message — grab the OTP over an API, route mail with a rule, or read it in the UI.
Open source and self-hostable, so your mail never leaves your infrastructure.
It's also reachable from an MCP client like Claude Code or
Cursor, so an agent can read the same inbox you can.
Open source under AGPL-3.0, with an optional commercial layer under ee/.
Features
- Instant inboxes on domains you control, with impersonation and length guards on creation
- Real-time ingestion via Resend webhooks, with an optional async (Redis/BullMQ) path for
high-volume mail
- Threading & full-text search — subject/body search, tag and category filters, thread
grouping
- Automations that run against incoming mail
- Agent access via MCP — list, search, and read inboxes and messages (including one-time
codes) from Claude Code, Claude Desktop, Cursor, or VS Code, using an API key you already have
(setup)
- A published REST API (
/api/v1) secured by scoped API keys, alongside the dashboard API
- Multi-tenant by design — organizations, memberships, and a read/write scope split enforced
at the type level, not just in route handlers
Quick start
Docker (Community Edition)
No Node or local Postgres install needed — pulls the published image.
mkdir programmableinbox && cd programmableinbox
curl -fsSLO https://raw.githubusercontent.com/roshansingh/programmableinbox/main/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/roshansingh/programmableinbox/main/.env.quickstart.example
cp .env.quickstart.example .env
# edit .env: set POSTGRES_PASSWORD, AUTH_JWT_SECRET (openssl rand -base64 32), RESEND_WEBHOOK_SECRET,
# RESEND_API_KEY, and EMAIL_INBOX_ALLOWED_DOMAINS — a placeholder is fine to start exploring
docker compose pull
docker compose up -d
# → http://localhost:4000, register a new account at /auth/register
See the Docker quickstart guide
for wiring up real inbound mail via Resend, upgrading, and troubleshooting.
From source (development)
For hacking on the codebase — hot reload and seeded test data. This isn't the
supported way to self-host; see
the Docker quickstart guide
for that.
Requirements: Node.js 24+, PostgreSQL 14+, and optionally Redis 6+ (only for async webhook
processing).
# Install dependencies
npm install
# Configure
cp .env.example .env
# fill in DATABASE_URL, AUTH_JWT_SECRET, and the other required values — see .env.example
# Set up the database
npx prisma migrate dev
npx prisma db seed # creates [email protected] / password123
# Run it
npm run dev
# → http://localhost:4000
Log in with [email protected] / password123, or register a new account.
Documentation
- docs.programmableinbox.com — the public docs: product
overview, self-hosting, the API reference, SDK usage, and MCP setup
- Architecture — start here to understand how the app fits
together: request flow, auth, multi-tenancy, email ingestion, search, the MCP server, and more,
broken into one doc per topic
- Environment variables — every variable, documented; validated at boot by
lib/config/ (see configuration.md)
- Client SDKs — generated Python, Go, TypeScript, Java, and C# clients for the
v1 API
- Operator guide — running async webhook
processing in production
- Logging — structured logging setup
Commands
npm run dev # Dev server on :4000 (Turbopack)
npm run build # Production build
npm run start # Run the production build
npm run lint # ESLint
npm run test # Run the test suite once
npm run test:watch # Watch mode
npx prisma studio # Browse the database
See testing.md for how the test suite is structured, including
the integration suite that runs against a real Postgres instance.
License
The core of this repository is licensed under AGPL-3.0. Code under ee/, if
present, is licensed separately under ee/LICENSE — see
commercial-layer.md for how the two fit together. A
build with ee/ removed is a complete, fully functional open-source edition.
Contributing
Issues and PRs are welcome. docs/architecture/README.md is the
best starting point for understanding the codebase before making a change. Run npm run test
before opening a PR — the suite should stay green.
