Matthew Meszaros
a7518a8558
* feat: rewrite the self-hosting docs against repo ground truth: turn the deployment guide into a full self-host guide (quick start with first-admin bootstrap via make grant-admin, .env secrets with exact key formats, PUBLIC_HOST derivation and HTTPS reverse-proxy vars, provider switches with build-tag caveats, mailbox OAuth, remote worker enrollment via SSH or wmenroll tokens, real CI image tags, upgrades and backups), rewrite the events page around the real NATS/Kafka bus topics and {type,body} envelopes, fix Kafka-era and make-target claims in architecture/local-development/deploy README, add API_PUBLIC_URL and drop the dead LOG_DISCORD_WEBHOOK_URL in env.example, and remove the docker-compose.kafka.yml comment pointing at a file that does not exist
* feat: make the self-hosting docs visual and skimmable by adding a Mermaid MDX component (client-rendered, theme-aware) to the docs site, condensing the self-host guide around a control-plane topology diagram, a worker enrollment sequence diagram, a dashboard screenshot, and symptom/check troubleshooting + optional-subsystem tables, and adding an execution-plane flowchart to the architecture page
* feat: stop the docs root flashing a 'Continue to the Warmbly docs' link before redirecting by navigating with an inline location.replace that runs during HTML parse, and demoting the visible link and meta refresh to no-JS fallbacks inside noscript
* feat: cut docs bulk and duplication by deleting three orphaned API pages that were stale forks of the reference section and were unreachable from the sidebar (porting their unique social sign-in, promo-code, and referral endpoints into api/reference/account-org.mdx as compact tables), condensing the deliverability and warmup guides to roughly half their length around tables instead of prose, replacing prose em dashes across the guides and MCP pages, and adding the required trailing slashes to internal links in 24 files
* feat: condense the sequences guide by about 40 percent, folding the switch-step deciders and branch conditions into tables and cutting restated prose while keeping every rule about threading, instant branches, reply matching, and stop on reply
* feat: condense the automations, unibox, advisor, and expressions guides by roughly 40 percent each, folding trigger lists, action catalogs, sending controls, and advisor checks into tables, adding a trigger-condition-action flow diagram to automations, and cutting restated prose while preserving every threshold, permission boundary, and rule
* feat: condense the mailboxes, campaigns, analytics, and team-roles guides by roughly 45 percent each, replacing prose walks through providers, rotation modes, lead statuses, counting rules, A/B confidence, and the permission matrix with compact tables and collapsing the four-way role grid into one capability table plus a one-line mapping
* feat: condense the AI-steps, security, and contacts-CRM guides by roughly 40 percent, turning sign-in methods, AI step modes, switch deciders, credit and failure behavior, import field mappings, and deal views into tables while keeping every safety boundary and dedupe rule
* feat: condense the meetings, notifications, AI-credits, and AI-assistant guides by roughly 40 percent, merging notification categories and their defaults into one table, collapsing credit costs, spend controls, and plan allowances into tables, and tightening the assistant page around its approval and permission boundaries
* feat: condense the integrations, collaboration, zapier, and make guides by roughly 35 percent, grouping the thirty-row Zapier and Make action lists into eight labelled areas, folding CRM default field mappings and presence indicators into tables, and promoting the destructive-action and unattended-delete warnings into callouts
* fix: correct three factual errors in the development docs: NOTIFICATION_EMAIL_DAILY_CAP=0 means uncapped rather than disabled (overEmailBudget returns false at limit<=0, so documenting it as a kill switch inverted the behavior), and the worker-SSH and warmup-pool migration citations in architecture.mdx pointed at pre-squash filenames that no longer exist or now belong to unrelated migrations, so both now cite the tables in 000001_baseline.up.sql
* feat: add the missing docs SEO primitives: a build-time sitemap.xml covering all 64 pages, a robots.txt that points at it and keeps the llms.mdx and og mirrors out of the index as duplicate content, and per-page canonical plus richer OpenGraph URL/title/description metadata
* fix: use the single real team@warmbly.com address everywhere a human is told to write in, replacing the invented hello/sales/legal/support inboxes across the marketing site, the transactional email footer, and the admin outreach composer default Reply-To (which pointed replies at a mailbox that does not exist), and collapse the contact page's two-inbox framing into one inbox with one published response time
The open-source agentic cold email and warmup platform.
Features · How it works · Quick start · Self-hosting · Docs · Community · Support
⭐ Help us reach more senders and grow the Warmbly community. Star this repo!
Warmbly
Warmbly runs cold email campaigns from the mailboxes you already own and warms them so they keep landing in the inbox. Opens, clicks, and replies land in a shared dashboard the moment they happen, and it's AI-native, so your team and its agents work in it together, live.
https://github.com/user-attachments/assets/378a510a-bb99-425f-925e-04300184938b
Features
- Campaigns - multi-step sequences with per-mailbox caps and spacing
- Unified inbox - every mailbox and reply in one place
- CRM - contacts, pipelines, deals, tasks, meetings
- Warmup - a pool of monitored mailboxes, not throwaway accounts
- Deliverability - bounces, complaints, suppression, inbox placement
- Automations - visual reply playbooks with AI steps
- Integrations - HubSpot, Slack, Zapier, REST API, webhooks
- Realtime - live presence and edits across your team
How it works
Warmbly splits into a control plane (backend API, consumer, Postgres, Redis, and the event bus) that owns all state, and an execution plane of interchangeable Go workers that send and sync mail. Workers never touch Postgres, and outbound mail leaves through each mailbox's own provider, not the worker's IP, so you add throughput by running more workers.
flowchart LR
MB["Your mailboxes"] --> API
subgraph CP["Control plane"]
direction TB
API["Backend API"] --> DB[("Postgres")]
API --> BUS{{"Event bus"}}
end
BUS --> W1["Worker"]
BUS --> W2["Worker"]
BUS --> W3["Worker"]
W1 --> P["Gmail · Microsoft · SMTP"]
W2 --> P
W3 --> P
P --> R["Recipients"]
Secrets use envelope encryption, with a local AES master key by default or AWS KMS if you prefer. Full write-up in the architecture docs.
Quick start
You need Docker, Go 1.25, and pnpm.
git clone https://github.com/warmbly/warmbly && cd warmbly
make dev
One command brings up the backing services in Docker, applies migrations, seeds
demo data, and starts the backend, worker, and dashboard natively. Open
http://localhost:5173 and log in with dev@warmbly.com / password123. Full
setup lives in the
local development guide.
Self-hosting
Warmbly runs with no cloud account of any kind: no AWS, no GCP, no Stripe, no Kafka. One command brings up the whole platform on local, open-source pieces:
git clone https://github.com/warmbly/warmbly && cd warmbly
make up # or: docker compose up --build
Every external dependency is picked by an environment variable, so you swap in a cloud service only if you want one:
| Concern | Self-host default | Optional / cloud |
|---|---|---|
| Database | PostgreSQL 16 | RDS / Cloud SQL, any Postgres |
| Cache | Redis (or Valkey) | ElastiCache |
| Event bus | NATS JetStream | Kafka (-tags kafka) |
| Blob storage | Filesystem | S3, MinIO, R2, B2 |
| KMS / root key | Local AES master key | AWS KMS |
| Payments | Off (everything unlocked) | Stripe |
Scaling is by mailboxes and workers, not IPs. Reaching it from another machine, connecting Gmail, and day-2 operations are all in the self-hosting guide.
Documentation
The full docs live at docs.warmbly.com.
| Read this | To learn |
|---|---|
| Local development | Every make target, the native services, and how seeding works |
| Architecture | How the control plane and workers split the job, plus the encryption model |
| Self-hosting guide | Taking it to production and scaling the worker fleet |
| API reference | Endpoints, auth, permissions, and webhooks |
Community
Have a question, found a bug, or want to shape where Warmbly goes next?
- Discord - chat with the team and other senders
- GitHub Issues - report bugs and request features
- X / @WarmblyHQ - follow along for updates and releases
- Email - reach us at
team@warmbly.com
Support and enterprise
Note
Need a hand? We are happy to help. Ask in Discord, open a GitHub issue, or email
team@warmbly.com, and someone on the team will get back to you.Running Warmbly at scale, or would you rather we run it for you? We offer enterprise support and managed infrastructure: we can host and operate the whole platform for your organization, help you deploy and scale the worker fleet, tune deliverability, migrate your sending onto Warmbly, and stand behind it with a support agreement built around your team. Tell us what you need at
team@warmbly.comor reach out on X.
Star the repository ⭐
Contributing
Pull requests are welcome. Keep each one to a single logical change, and open an
issue first for larger design or product changes. Before you open a PR, run the
checks for the tree you touched (make fmt and make lint for Go, pnpm typecheck and pnpm lint for the frontends). See CONTRIBUTING.md.
Security
Found a vulnerability? Email team@warmbly.com instead of opening a public issue.
We prefer responsible disclosure and credit reporters in the release notes.
License
Apache License 2.0. Copyright 2026 Mindroot Ltd. See LICENSE.