I just open-sourced the cold email engine behind WarmySender. It is a self-hosted Instantly alternative: you run it with docker compose up, connect your own mailboxes, and the app sends from those mailboxes on your server.
The part I want to walk through here is not the UI. It is how sending actually works, and why an AI agent connected over MCP cannot turn it into a blast tool.
The constants, the queue, and the agent lock all live in the public repo. I am describing v0.1.0 as it is today.
What you get when you start it
git clone https://github.com/warmysender-oss/warmysender.git
cd warmysender
docker compose up
Open http://localhost:3000. The first account is the admin. Compose brings up the app, the worker, and PostgreSQL. Jobs stay in Postgres through pg-boss.
On a laptop, development defaults are fine. NODE_ENV=production refuses those defaults, so you have to set ENCRYPTION_KEY and SESSION_SECRET before you expose the server.
The worker is a loop, not a firehose
The worker (apps/worker/src/index.ts) starts a PgBoss client on the same Postgres database, then creates three queues:
| Queue | Cron | What it does |
|---|---|---|
heartbeat |
* * * * * (every minute) |
Writes a heartbeat so you can see the worker is alive |
| inbox poll |
*/5 * * * * (every five minutes) |
Polls IMAP, files replies and bounces |
send-tick |
* * * * * (every minute) |
Asks the scheduler who is allowed to send right now |
The important one is send-tick. Every minute the worker runs executeSendTick. That function does not "send the campaign." It asks the scheduler whether this mailbox, at this moment, is allowed to send one email.
A tick can fail. When it does, the worker logs it and rethrows, so a broken send cycle is visible in the logs instead of disappearing.
Inbox mail is on a slower loop on purpose. Replies and bounces matter, but they do not need to be checked every minute.
Caps are constants, then they are enforced again at send time
The numbers are not only in the README. They are named constants in packages/core/src/scheduler/constants.ts:
DEFAULT_DAILY_CAP = 30HARD_MAX_DAILY_CAP = 50RAMP_CAP_DAYS_1_TO_7 = 10RAMP_CAP_DAYS_8_TO_14 = 20- Default random gap: 4 to 9 minutes
- Transient SMTP retries: 3 attempts, with 5-minute then 15-minute backoff
- Three sign-in failures in a row pause the mailbox
- After an auth failure, the worker waits 30 minutes before trying that login again
packages/core/src/scheduler/caps.ts turns those into the cap for today:
-
clampDailyCapfloors the configured cap and never returns more than 50. Zero or negative means the mailbox cannot send. -
rampDayNumbercounts calendar days fromrampStartedOnin the mailbox's local date. If the clock is skewed and "today" is somehow before the start date, it stays on day 1 so the ramp cannot be skipped. -
effectiveDailyCaptakes the lower of the clamped mailbox cap and the ramp cap. Days 1 to 7 are 10. Days 8 to 14 are 20. After that, the mailbox's own cap applies, still clamped at 50.
The form validation matches this. validateDailyCap accepts 30 and 50, and rejects 51, 0, fractions, and junk strings. You cannot type 200 into the mailbox form and have it stick.
A send has to pass a checklist
packages/core/src/scheduler/evaluate.ts is the gate. Before a mailbox sends, the scheduler checks, in order:
- The schedule itself is valid (window and gap values make sense)
- Today is a sending day for that mailbox
- The current time, in the mailbox's timezone, is inside its sending window
- The ramp day can be computed
- Today's effective cap is known, and the mailbox is still under it
- The random gap since the last send has elapsed
Fail any one of those and that tick does not send. The reasons have names (outside_window, gap_not_elapsed, invalid_schedule, and so on), which is what you want when you are debugging a quiet mailbox at 11pm.
One email at a time per mailbox is also a rule, not a preference. The gap (default 4 to 9 minutes) is why a tick every minute does not mean a send every minute.
Where agents are locked out
The app ships a REST API (/api/v1) and an MCP server (/mcp) for Claude, ChatGPT, Cursor, Codex, OpenClaw, Hermes Agent, and other MCP clients. Agents can build a campaign. They cannot send a message themselves, and they cannot raise a limit.
The MCP instructions say so in plain words: "Tools never send directly and can never raise a limit; the scheduler sends inside safe limits."
The tools in apps/server/src/mcp/tools.ts include things like create_contact, create_campaign, add_campaign_step, start_campaign, pause_campaign, enroll, list_replies, and draft_reply. There is a draft_reply tool. There is not a "send this reply now" tool. A draft stays a draft until a person sends it from the inbox.
The API also strips a class of fields on the way in. apps/server/src/api/limits.ts walks every nested object in a request and rejects keys such as daily_cap, min_gap_minutes, window_start, and ramp, no matter the capitalization or hyphens. The response is 403 with limit_locked and the message: "An agent can never raise a limit. Daily cap, ramp, sending window, and the gap between sends are fixed in code."
That is the design I wanted in the open version. The scary part of handing a campaign to an agent is not that it can write a sequence. It is that it might try to send 2,000 emails overnight. In this codebase, that request should fail before the worker ever sees it.
What v0.1 does not do
I want this to be accurate, because v0.1 is the first public release.
- It sends the message as you wrote it. There is no open or click tracking.
- Warmup, email verification, the leads database, LinkedIn, and Instagram stay in WarmySender Cloud. The open-source app can optionally use warmup and verification through a WarmySender API key. The core app runs with no key.
- Microsoft 365 / Outlook needs your own Entra app, documented in the repo.
If you try it, the repo and GitHub Discussions are the right place to tell me what breaks: https://github.com/warmysender-oss/warmysender
Top comments (0)