MailForge Email Outreach Platform

A fail-closed, no-code email operations system built around Baserow and n8n.

MailForge combines a Baserow operating interface with n8n automation for recipient import, email validation, segmentation, A/B assignments, batching, provider delivery, event processing, unsubscribe handling, reporting, and emergency controls.

The public repository contains sanitized configuration and synthetic sample data. Real sending is disabled by default and must pass explicit safety gates.

✨ Features

• Import and normalize recipient data from CSV, forms, and webhooks.
• Validate email records before they enter a campaign.
• Build segments and deterministic A/B assignments.
• Create queued batches with controlled ramp-up behavior.
• Keep real delivery disabled unless global and campaign-level gates agree.
• Support dry-run and one-recipient live-test workflows.
• Process delivery, bounce, complaint, click, open, and unsubscribe events.
• Maintain suppression lists and non-enumerable unsubscribe tokens.
• Enforce daily limits and expose an emergency-stop workflow.
• Store operational records, incidents, failures, and metrics in Baserow.
• Provide synthetic CSV seeds, schema blueprints, QA documentation, and mocked smoke tests.

No delivery-rate, conversion, revenue, or throughput metrics are claimed.

🧰 Tech Stack

Layer	Technology
Operator UI and data	Baserow 2.3.3
Automation backend	n8n 2.28.0
Local runtime	Docker Compose, Nginx preview proxy
Email providers	Brevo, Amazon SES, generic SMTP adapters
Configuration	Environment variables and n8n credentials
Verification	Python unittest, Node.js mocked workflow harness
Data exchange	CSV, JSON, HTTP webhooks

🚀 Getting Started

Prerequisites

• Docker Desktop with Docker Compose
• Python 3.11 or newer
• Node.js 20 or newer
• A modern browser

Installation

git clone https://github.com/wtyck/mailforge.git
cd mailforge
cp .env.example .env

# Start Baserow
cd baserow-local
docker compose up -d
cd ..

# Prepare n8n's local environment file, then review every value.
cp .env.example n8n-local/.mailforge.local.env
chmod 600 n8n-local/.mailforge.local.env

# Start n8n and the preview proxy
cd n8n-local
docker compose up -d
cd ..

Create a local Baserow account, generate a database token, import the CSV files in the order documented in baserow/IMPORT_ORDER.md, and then import the JSON workflows from n8n/workflows/.

Usage

Run static package checks:

python3 scripts/verify_package.py

Run the mocked end-to-end automation test. It does not contact Baserow, n8n, an email provider, or a recipient:

node scripts/smoke_test_workflows.mjs
python3 -m unittest discover -s tests -p 'test_*.py'

Start with EMAIL_REAL_SEND_ENABLED=false. Follow docs/ADMIN_SETUP_RU.md, docs/SECURITY_RU.md, and qa/ACCEPTANCE_CHECKLIST_RU.md before considering any live delivery.

📚 API Reference / Configuration

Webhook surface

Method	Endpoint	Description
POST	/webhook/mailforge/website-client-request	Accept a secured website request.
POST	/webhook/mailforge/product-event	Record a secured product event.
POST	/webhook/mailforge/provider-event	Process authenticated provider events.
GET	/webhook/mailforge/unsubscribe	Apply idempotent unsubscribe handling.
POST	/webhook/mailforge/emergency-stop	Disable sending through protected controls.

See n8n/API_CONTRACT.md for request headers and response contracts.

Core environment variables

Property	Type	Description	Default
BASEROW_API_URL	URL	Baserow API root.	https://api.baserow.io
BASEROW_API_TOKEN	secret string	Database token stored outside source control.	none
N8N_WEBHOOK_API_KEY	secret string	Shared API-key guard for inbound workflows.	none
EMAIL_PROVIDER	string	Delivery adapter identifier.	none
EMAIL_REAL_SEND_ENABLED	boolean	Global live-send gate.	false
PUBLIC_BASE_URL	URL	Public n8n URL used for callbacks and unsubscribe links.	http://localhost:5678
BASEROW_BATCH_SIZE	integer	Number of recipients prepared per batch.	50
BREVO_HTTP_TIMEOUT_MS	integer	Brevo request timeout.	30000

The complete configuration contract is in .env.example. Never commit .env or n8n-local/.mailforge.local.env.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/short-description.
3. Keep real sending disabled in tests and examples.
4. Run all static, mocked workflow, and Python tests.
5. Push the branch and open a focused pull request.

Never commit credentials, real recipient data, provider payloads, or customer information.

📄 License

Released under the MIT License. Copyright © 2026 wtyck.