Skip to main content
Glama
WarmySender

WarmySender

Official

WarmySender — open-source cold email

Open-source cold email you can self-host. The open-source Instantly alternative.

Hosted version: WarmySender — adds warmup, email verification, leads and LinkedIn. New accounts get Pro at $9/month with the sign-up offer → https://warmysender.com

License: AGPL-3.0 Release CI Stars Docker image

Demo

WarmySender open-source cold email: dashboard, sequences, contacts, mailboxes and inbox in light and dark mode

Seeded demo data uses .test domains only.

Related MCP server: coldforge

Features

  • docker compose up runs the app, the worker, and PostgreSQL. Jobs stay in Postgres through pg-boss.

  • Email and password accounts. The first visitor is the admin and invites teammates by link.

  • API keys (create, name, revoke). A key is shown once and stored hashed.

  • Any SMTP/IMAP mailbox, with presets for Gmail / Google Workspace (App Password), Zoho, Hostinger, Fastmail, and custom hosts, plus Microsoft 365 / Outlook through the self-hoster's own Entra app.

  • Per-mailbox daily cap, sending window, random gap, and a ramp for new mailboxes.

  • CSV import, lists, and a global suppression list.

  • Sequences with variables and fallbacks, same-thread follow-ups, and a launch check that lists problems in words.

  • v1 sends the message as you wrote it, with List-Unsubscribe and one-click unsubscribe, and without open or click tracking.

  • A unified inbox. A real reply stops the sequence. Auto-replies are labeled and do not stop it. Bounces are suppressed.

  • Stats per campaign, step, and mailbox.

  • REST API (/api/v1) and MCP (/mcp) for Claude, ChatGPT, Cursor, Codex, OpenClaw, Hermes Agent, and any other MCP client.

  • Optional WarmySender connect for list verification, mailbox warmup, and a leads-search link. The core app runs with no WarmySender key.

  • A DNS deliverability check (SPF, DKIM, DMARC, MX) on each mailbox, and pnpm doctor / docker compose run app doctor.

Works with your AI agent

Claude, ChatGPT, Cursor, Codex, OpenClaw, Hermes Agent, and any client that speaks MCP. Connection snippets for all six are in docs/agents.md.

npx skills add warmysender-oss/warmysender

Fork it and have your agent build the tool you want. Layout and commands for that agent live in AGENTS.md and CLAUDE.md.

Quick start

Let your agent set it up

Paste this into Claude Code, Codex, or Cursor:

Set up open-source WarmySender from https://github.com/warmysender-oss/warmysender in this folder.

1. Clone the repository if it is not already here.
2. Copy .env.example to .env and fill every variable that file documents. Do not commit .env. Demo and test addresses use .test domains only.
3. Start the stack with `docker compose up`.
4. Open http://localhost:3000. The first account becomes the admin.
5. Leave the sending caps, window, gap, and ramp as they are. Agents create and start campaigns. The scheduler sends. An agent cannot raise a limit, and a reply draft stays a draft until a person sends it from the inbox.

Or do it yourself

  1. Clone the repository and move into it.

    git clone https://github.com/warmysender-oss/warmysender.git
    cd warmysender
  2. Start the stack. On a laptop, Compose supplies development defaults, so a .env file is optional. NODE_ENV=production refuses those defaults.

    docker compose up
  3. Open http://localhost:3000 and create the first account. That account is the admin.

Before you expose the server, copy .env.example to .env and set ENCRYPTION_KEY and SESSION_SECRET the way that file describes (openssl rand -base64 32). Details, including Coolify, Dokploy, Portainer, and Railway, are in docs/self-hosting/README.md.

Release tags publish ghcr.io/warmysender-oss/warmysender. The Compose file in the repo builds the local Dockerfile (build: .).

Safe by default

Limits are code. An agent cannot raise them.

  • Each mailbox sends at most its daily cap. The default is 30. The hard maximum is 50.

  • A new mailbox ramps: 10 a day on days 1–7, 20 a day on days 8–14, then that mailbox's own cap.

  • Sends happen only inside the mailbox's sending window and timezone, and only after a random gap since its last send (default 4–9 minutes). One email at a time per mailbox.

  • A real reply stops that contact's sequences. A bounce suppresses the contact. Suppressed contacts are skipped.

  • Every email can be unsubscribed in one click (List-Unsubscribe and List-Unsubscribe-Post).

  • MCP and API tools create and start campaigns. The scheduler sends. Reply drafting saves a draft a person sends from the inbox.

Open source vs WarmySender Cloud

Open source (self-host)

WarmySender Cloud

Cold email sequences

Yes

Yes

Unified inbox

Yes

Yes

REST API

Yes

Yes

MCP for AI agents

Yes

Yes

Warmup network

Connect a WarmySender key

Yes

Email verification

Connect a WarmySender key

Yes

Leads database

Connect a WarmySender key

Yes

LinkedIn

—

Yes

Instagram

—

Yes

Managed hosting

—

Yes

WarmySender open source vs hosted cold email tools

Instantly, lemlist, and Smartlead are closed-source hosted services. This repository is self-hosted cold email under the GNU AGPL-3.0.

WarmySender (open source)

Instantly, lemlist, Smartlead (hosted)

Source code open

Yes. This repository.

Closed source

Self-host on your own server

Yes. docker compose up runs the app, the worker, and PostgreSQL 16 on a machine you control.

Hosted only

Licence

GNU AGPL-3.0

Closed source

Your data stays on your server

Yes for the app you run. Accounts, contacts, messages, and mailbox secrets stay in your Postgres database. Secrets are encrypted at rest. Connecting warmup sends that mailbox login to your WarmySender account.

Hosted only

AI agents over MCP with safe limits

Yes. Claude, ChatGPT, Cursor, Codex, OpenClaw, and Hermes Agent. Tools create and start campaigns. The scheduler sends. A tool cannot raise a limit or send a message.

Not compared here

Warmup network

No warmup network in this app. Warmup is a WarmySender Cloud feature you connect with a key.

Not compared here

Costs

Self-hosting costs your server and your mailboxes. WarmySender features (warmup, verification, leads, LinkedIn) cost your WarmySender plan. New accounts get Pro at $9/month with the sign-up offer → https://warmysender.com

Self-hosting

FAQ

Is there a free open-source alternative to Instantly?

Yes. This repository is open-source cold email you self-host, under the GNU AGPL-3.0, with no licence fee. Instantly is a closed-source hosted service. You run the sequences, inbox, REST API, and MCP server on your own machine. Warmup, verification, leads, and LinkedIn stay on the hosted WarmySender plan linked above.

Can I self-host cold email software?

Yes. WarmySender is self-hosted cold email. docker compose up starts the app, the worker, and PostgreSQL 16, and http://localhost:3000 is the UI. The first account is the admin. Docker, Coolify, Dokploy, Portainer, and Railway are documented in docs/self-hosting.

What do I need to run it?

Docker with Compose v2 is the supported install, and a source checkout uses Node 22, pnpm, and PostgreSQL 16. You bring your own mailboxes. Before you expose the server, set ENCRYPTION_KEY and SESSION_SECRET the way .env.example describes. NODE_ENV=production refuses the development defaults published in the Compose file.

Does it work with Gmail and Outlook?

Yes. Gmail and Google Workspace connect over SMTP and IMAP with an app password, and the same form has presets for Zoho, Hostinger, Fastmail, and a custom host. Microsoft 365 and Outlook use an Entra app you register for your own server. The steps are in docs/MICROSOFT-APP.md.

How does it keep my mailboxes safe?

The limits are code, and an agent cannot raise them. Each mailbox sends at most its daily cap (default 30, hard maximum 50), and a new mailbox ramps at 10 a day on days 1–7 and 20 a day on days 8–14. Sends stay inside that mailbox's window and time zone, one at a time, after a random gap (default 4–9 minutes). A real reply stops that contact's sequences, a bounce suppresses the contact, and three sign-in failures in a row pause the mailbox.

Can AI agents like Claude or ChatGPT run my campaigns?

Yes. Claude, ChatGPT, Cursor, Codex, OpenClaw, and Hermes Agent connect over MCP at /mcp with an API key, and the same actions are on the REST API. Those tools create and start campaigns. The scheduler sends, inside the caps, window, gap, and ramp, and a reply tool saves a draft a person sends from the inbox. Snippets for all six are in docs/agents.md.

Does it do email warmup?

Warmup is a WarmySender Cloud feature you can connect with a key. This app does not run a warmup network, and sequences, the inbox, and the scheduler work with no key. For an SMTP or IMAP mailbox, Settings asks you to confirm before the mailbox login is sent to your WarmySender account. Microsoft mailboxes are warmed by signing in inside WarmySender.

Is it really free?

The software is free to run, and there is no licence fee for this repository. Self-hosting costs your server and your mailboxes. Warmup, email verification, leads, and LinkedIn use a WarmySender plan. New accounts get Pro at $9/month with the sign-up offer at https://warmysender.com.

What licence is it?

GNU Affero General Public License v3.0. You can run, study, and change the code. If you run a modified version as a network service, the AGPL requires you to offer the corresponding source to users of that service. The text is in LICENSE.

How is it different from Instantly, lemlist or Smartlead?

You self-host this program, the source is AGPL-3.0, and the database stays on your server. Instantly, lemlist, and Smartlead are closed-source hosted services. People looking for a lemlist alternative or a Smartlead alternative get the same deal as the Instantly alternative in the first line: your server, your mailboxes, and MCP for Claude, ChatGPT, Cursor, Codex, OpenClaw, and Hermes Agent, with the limits above.

Contributing

See CONTRIBUTING.md. Checks for this repo:

pnpm typecheck
pnpm lint
pnpm test

Community

Questions and ideas go to GitHub Discussions.

Star the repository ⭐

If this is useful, star warmysender-oss/warmysender.

Security

Report vulnerabilities through https://warmysender.com/support (see SECURITY.md). Do not open a public issue for a security problem.

License

GNU Affero General Public License v3.0. If you run a modified version as a network service, the AGPL requires you to offer the corresponding source to users of that service.

Support for the project and the hosted product: https://warmysender.com/support

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables cold email marketing automation with campaign management, lead tracking, deliverability optimization, and analytics, integrating with 113 tools via zero-config NPX installation.
      1,089 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables personalized cold email outreach through research, drafting, template management, and deliverability checks, all locally with no required API keys.
      7
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Agent-native cold-email infrastructure providing ~12 high-level tools for domain setup, mailbox provisioning, campaign launch, inbox management, and metrics, all operated via MCP or CLI.
      28
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for managing cold-email infrastructure: buy domains via Porkbun, import them into CheapInboxes, provision Google/Microsoft mailboxes, and sync credentials to platforms like Instantly and Smartlead.
      MIT