Matthew Meszaros
e143cb0628
* feat: cut the README quick start and self-hosting sections down to the install command, one paragraph of what it does, and links out to the local development, first-run, deployment and warmblyctl docs pages, dropping the recovery if/then table, the MAIL_TRANSPORT invitation note and the dependency matrix that all duplicate those pages * feat: give warmblyctl an API-key half so agents and scripts can operate any Warmbly instance including the hosted one, adding a raw passthrough (warmblyctl api get/post/patch/put/delete <path> with --data taking a literal, - or @file, and --idempotency-key) plus eleven typed families (me, campaign, contact, mailbox, inbox, analytics, settings, webhook, apikey, template, crm) driven by one spec table that generates dispatch, flags, per-command help and the request, covering list/get/create/update/delete, sequence steps, sender pools, preflight/start/stop/test-email, contact notes/timeline/import/export, mailbox behavior/verify/send and the six warmup controls, unibox threads/reply/compose/seen/agent-drafts/scheduled sends, outreach settings, webhook secrets and deliveries, and API key self-service, authenticated with Bearer wmbly_ keys from WARMBLY_API_KEY against WARMBLY_API_URL falling back to API_PUBLIC_URL then the hosted service, printing the API's JSON untouched and surfacing the error envelope's code and request_id with Retry-After on 429, while the DB-direct operator commands and their trust model stay exactly as they were * feat: ship two in-repo agent skills so AI assistants working against Warmbly discover the right warmblyctl half on their own, .claude/skills/warmbly-api teaching product operation over the API commands (key and URL setup including the seeded local dev key, the eleven command families, pagination and error-code and Idempotency-Key conventions, and a sending-safety section that names the six commands that put real mail on the wire and holds agents to preflight before start and the 50/day default cap) and .claude/skills/warmbly-ops teaching instance administration over the DB-direct commands (status --json as the contract to parse, the recovery command table, TTY versus -T piping, Redis-down behaviour, and org export/import handling including --dry-run first and the sensitivity of credential archives), each pointing at the other for what it does not cover, narrowing the .gitignore .claude/ rule to .claude/* with !.claude/skills/ so personal agent state stays local while the skills ship * feat: document warmblyctl's new API half on the warmblyctl reference page, reframing the intro around the two halves and their two trust models and replacing the 'no HTTP surface and never will' line with the accurate claim that the CLI never serves HTTP while the API commands are a client of the already-gated public API, adding WARMBLY_API_KEY and WARMBLY_API_URL to the environment table with the API_PUBLIC_URL-then-hosted fallback, renaming The commands to The operator commands, and adding an API commands section covering key setup, the eleven command families, the raw /v1 passthrough with curl-style --data forms, the pagination, idempotency-key and Retry-After conventions, a warning callout naming the six commands that put real mail on the wire with preflight-before-start guidance, and a pointer to the shipped .claude/skills agent skills, plus API authentication and permissions links in See also * feat: move the shipped agent skills from .claude/skills/ to a top-level skills/ directory so they follow the convention other repos use for distributable agent skills rather than living inside Claude Code's personal state directory, restoring the .gitignore .claude/ rule to its original form since nothing tracked lives under it anymore, and updating the warmblyctl reference's For AI agents section to name skills/ and show installing a skill by copying it into the agent's own skills directory or pointing the agent at SKILL.md directly * feat: clear the Security Scan failure by lifting the two flagged indirect Go modules past their fixed versions, github.com/moby/go-archive from v0.2.0 to v0.3.0 for the CVE-2026-17106 tar path traversal and golang.org/x/mod from v0.37.0 to v0.40.0 for the CVE-2026-56864 and CVE-2026-56865 GOSUMDB and GOPROXY forgery pair, with the x/sys, x/text and x/tools bumps go mod tidy pulls along * feat: take the Trivy dependency scan off the PR gate and restructure CI the way larger projects do, because a full-repo CVE scan on every pull request goes red the morning any dependency gets a new advisory regardless of what the PR touches, which is exactly how this branch failed on two indirect Go modules it never went near, moving the scan to its own security.yml running weekly, on demand, and on main pushes that change a dependency manifest, pinned to trivy-action 0.36.0 instead of @master, extracting the pnpm+Node+frozen-install boilerplate repeated across the web, admin and site jobs into a .github/actions/setup-pnpm composite action with the store cached per lockfile, and collapsing the CI Status rollup's ten hand-enumerated result checks that had to be edited in two places per new job into a single contains(needs.*.result, ...) expression over failure and cancelled, all validated with actionlint
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
Open http://localhost:5173 and log in with dev@warmbly.com / password123;
the login code lands in Mailpit at http://localhost:18025. Every make target,
the native services, and how seeding works are in the
local development guide.
Warning
make devandmake upshare one database, and seeded fixture accounts claim the instance. Planning to self-host from the same machine? Read first run first.
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
That is the whole install: make up waits for the backend and prints a one-time
link that claims the instance and makes you its admin. You need Docker with
Compose v2 and about 10 GB of free disk. If anything looks wrong, make doctor
prints the instance state and every failing check.
From here the
self-hosting guide
covers the rest: your own secrets, production hardening, mail and single
sign-on, HTTPS, connecting Gmail and Microsoft mailboxes, scaling workers, and
backups. Account recovery and every operator command live in
warmblyctl, the CLI baked
into the backend image; it talks to the database directly, so it works when
signing in does not.
Documentation
The full docs live at docs.warmbly.com.
| Read this | To learn |
|---|---|
| Self-hosting guide | Step-by-step install, then production, backups, and scaling the worker fleet |
| First run | Claiming the instance, reissuing the setup link, and what to do when accounts already exist |
| Accounts and access | Registration modes, inviting people with or without a mail relay, SSO, and recovering access |
warmblyctl |
The operator CLI: creating accounts, setting passwords, granting admin, and instance status |
| Configuration reference | Every environment variable, its default, and whether changing it needs a restart |
| Instance health | The checks the admin panel runs against your deployment, and make doctor |
| Troubleshooting | The errors self-hosters actually hit, and the command that fixes each one |
| 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 |
| 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.