Loomail

The open-source lifecycle email engine. Your data, your transport, your LLM.

An AI-native alternative to Customer.io, Loops, and Mautic. Flows are written in plain language, compiled once by an LLM into a deterministic execution plan, and run by a pure Postgres-backed engine. No Redis, no Kafka, no message broker. One Docker image, one database.

Why it is different

Flows are prompts, compiled once. There is no drag-and-drop builder. You describe the flow ("welcome them, nudge them if they have not activated in 2 days, stop when they do"), the LLM compiles it into an inspectable plan, and the engine executes that plan deterministically. The AI never touches timing, targeting, or the send path.

Everything AI-written waits for a human. Generated emails queue in an approval inbox. You approve, reject, or let a trusted flow auto-send. The AI drafts; you publish.

Your stack, your keys. Emails go through your Resend or SMTP account. AI runs against your OpenAI-compatible endpoint (OpenAI, Anthropic, Gemini, Groq, Ollama). Postgres is the only infrastructure. Nothing phones home.

A retention grid, not a vanity dashboard. Contacts are bucketed by tenure and recency into a 4x4 grid. Each cell is an audience you can act on: create a flow, see who is there, watch the trend. The grid adapts to your product's natural rhythm.

Get running

git clone https://github.com/sasbaws2211-cloud/loomail.git && cd loomail
docker compose run --rm install
docker compose up

Open the claim URL printed to the console, enter your email, and you are the owner. The Quickstart walks through the rest: connect a transport, activate the library flow, send a test event, and receive a real email - all from the browser. About 5 minutes once images are cached.

What it does

Lifecycle state machine - 7 contact states (signed_up through resurrected) with engagement depth scoring and a payment overlay. Event-driven and time-driven transitions
Prompt-defined flows - compiled to deterministic plans. Triggers: events, lifecycle transitions, retention-grid segments. Steps with delays, conditions, send windows, exit conditions
Brain - compile, decide, draft, assess. Real LLM calls to any OpenAI-compatible endpoint, only at compile time and content time, never in the execution path
Approval queue - AI-drafted messages are held for human review by default; per-flow auto-approve when you trust it
Webhook steps - a flow step can call your own system (CRM, Slack, your product) instead of sending an email: signed, retried, with a delivery log
Inbound sources - connect Stripe, Paystack, Flutterwave or any JSON webhook (forms, Zapier, your own app) from the Integrate page: no code, a log of what arrived
Event ingestion - Segment-compatible /v1/track, /v1/identify, /v1/batch. Publishable and secret API keys, rate limits, browser snippet at /loomail.js
Transports - Resend (with open/click/bounce webhooks) and generic SMTP (including the Amazon SES SMTP endpoint)
Compliance built in - RFC 8058 one-click unsubscribe and a CAN-SPAM postal footer on every outgoing email, suppression list enforced before everything
Throttle and send windows - per-contact frequency caps, quiet hours, per-flow critical bypass
Knowledge base - pgvector-backed entries injected into compile and draft prompts
Dashboard - React SPA: Flows, Approvals, People, Lifecycle, Analytics, Knowledge Base, Settings, Integrate. Light and dark themes
Operator CLI - guided setup, login links, transport/LLM configuration, user recovery, deployment diagnostics

Not yet built

Schedule/cron triggers and manual-trigger enrollment (flows enroll on events, lifecycle transitions, and retention-grid segments today)
SES API-mode transport and non-Resend feedback webhooks (SES works today through its SMTP endpoint)
Knowledge base file upload and site crawl
Cross-device identity stitching (anonymous visitors are merged per browser, on identify; see guide/INGESTION.md)
Multiple workspaces per self-hosted instance

Documentation

Document	What it covers
Quickstart	Three commands to a running install, then a real email via the browser
Installation and Configuration	Every run mode, every environment variable and setting, migrations, upgrading, backups
Deployment	External Postgres, multiple instances, the role split, secrets that must match
Concepts and Guides	The model: events, contacts, compilation, approvals, content modes. Task guides
Flow Prompt Library	Working prompts to paste into the flow editor
Ingestion	Sending events: curl, browser snippet, React/Next.js/Vue and other frameworks, server SDKs (Node, Python, PHP/Laravel, Ruby/Rails, Go, Java), Segment compatibility, GTM
Data warehouse sources	Reading customers and events from Postgres, MySQL, SQL Server, Snowflake or BigQuery on a schedule
FAQ and Troubleshooting	Lost admin access, secrets, email not sending, AI features idle, backups, data egress
Contributing	The development model (open source, not open contribution)
Security	Vulnerability reporting

Changes are documented on the releases page; there is no separate changelog file.

Editions

Both editions share the same engine and schema. The distinction is how the product is operated.

	Community (this repo, MIT)	Cloud
Engine	Full lifecycle engine, all workers	Same engine
Brain	BYO LLM key (OpenAI-compatible or local/Ollama)	Same at launch; optimized hosted prompts later
Transport	Resend, SMTP (bring your own)	+ Zero-config hosted sending
Compliance	RFC 8058 one-click unsub, suppression, CAN-SPAM	Same + managed deliverability
Deploy	Self-host: single image, Postgres only	Fully hosted, zero-ops
Cost	Free (MIT)	Pay per email sent

Cloud adds zero-ops hosting and managed sending, not a better engine. The engine is identical.

Development (from source)

Requires Node.js 22+, pnpm 9.15+, and Postgres 16 with pgvector.

pnpm install
pnpm db:migrate   # apply migrations to DATABASE_URL from .env
pnpm dev          # API on :3000 (watch mode), dashboard dev server on :5173

Details and the production image are in Installation and Configuration.

License

MIT - see LICENSE. Bug reports welcome in GitHub Issues.