📧 MailPlatform — Documentatie

Laatst bijgewerkt: 2026-06-04 · server: vps-079bea53 (51.75.247.161) · mail.vindlokaal.eu

Inhoud

1. Architectuur
2. Services & poorten
3. Domeinen & mailboxen
4. Credentials
5. Orchestrator (AI-laag)
6. Dashboard
7. Bulk-mail campagnes
8. FAQ & self-learning
9. Nieuw domein toevoegen
10. Troubleshooting
11. Backup & recovery

1. Architectuur

                         ┌─────────────┐
   inkomende mail  ──▶   │   Postfix   │ ──▶ Dovecot LMTP ──▶ /var/vmail/<domain>/<user>/
   (port 25 SMTP)        │ multi-domain│         IMAP (port 993 TLS)
                         │  + Rspamd   │              ▲
                         └─────────────┘              │
                                                      │ master-user auth
                                                      │
                         ┌───────────────────────────────┐
                         │   Orchestrator (Node.js)      │
                         │  - polls IMAP every 60s       │
                         │  - classifies via OpenAI      │
                         │  - matcht FAQ                 │
                         │  - logs questions             │
                         │  - sends via Resend API       │
                         │  - rate-limited campagnes     │
                         │  - webhook :3001 (Resend)     │
                         └───────────────────────────────┘
                                      │
                                      ▼
                         ┌────────────────────────────┐
                         │   Pocketbase (port 8090)   │
                         │   - mailboxes / agents     │
                         │   - email_events           │
                         │   - faq_templates          │
                         │   - questions_log          │
                         │   - opt_outs               │
                         │   - campaigns / lists      │
                         └────────────────────────────┘
                                      ▲
                                      │ websocket realtime
                         ┌────────────────────────────┐
                         │  Dashboard (HTML/JS SPA)   │
                         │  /var/www/dashboard/       │
                         │  served by nginx :443      │
                         └────────────────────────────┘

2. Services & poorten

Service	Port	Status check	Logs
Postfix (SMTP)	25, 587 (submission)	`systemctl status postfix`	`/var/log/mail.log`
Dovecot (IMAP/LMTP)	993 IMAPS, 24 LMTP	`systemctl status dovecot`	`journalctl -u dovecot`
Rspamd (spam filter)	11334 (web UI)	`systemctl status rspamd`	`/var/log/rspamd/`
Pocketbase (backend)	8090 (lokaal)	`systemctl status pocketbase`	`journalctl -u pocketbase`
MailPlatform orchestrator	3001 webhook	`systemctl status mailplatform-orchestrator`	`journalctl -u mailplatform-orchestrator -f`
Nginx (reverse proxy)	80, 443	`systemctl status nginx`	`/var/log/nginx/`
Roundcube (webmail)	via nginx /webmail/	—	`/var/log/php-fpm/`
Redis (Rspamd cache)	6379 (lokaal)	`systemctl status redis`	`journalctl -u redis`

Belangrijk: Nginx proxy_pass naar Pocketbase MOET proxy_http_version 1.1; hebben anders breken realtime websockets en sommige queries (default HTTP/1.0 mismatch met Go HTTP/2 backend).

3. Domeinen & mailboxen

Domein	Mailbox	Brand	Status
vindlokaal.eu	info@, noreply@	VindLokaal (blauw)	active, verified
simpelscherm.nl	info@	Simpelscherm (paars)	active
displayscherm.nl	info@	Displayscherm (rood)	active
safescherm.nl	info@	Safescherm (oranje)	active
safetycircle.live	info@	SafetyCircle (groen)	active

Resend DKIM/SPF/DMARC records staan in OVH DNS van elk domein. Verification status checken:

curl -H "Authorization: Bearer $(cat /home/jojo/.credentials/resend-api-key)" \
  https://api.resend.com/domains | jq '.data[] | {name, status}'

4. Credentials

Alle gevoelige keys staan in /home/jojo/.credentials/ (chmod 600). Per file:

File	Inhoud
`mail-users.json`	Mailbox-wachtwoorden voor IMAP/SMTP
`mail-master-pw`	Dovecot master-user wachtwoord (orchestrator gebruikt dit om als elke mailbox in te loggen)
`resend-api-key`	Resend Pro API key ($20/maand plan)
`resend-webhook-secret`	HMAC signing secret voor webhook events
`openai-api-key`	OpenAI key (gpt-4o-mini, ~$0.0003 per email)
`ovh.json`	OVH API (appKey, appSecret, consumerKey)

Op de VPS staat een kopie in /etc/mailplatform/.env (systemd reads this).

5. Orchestrator (AI-laag)

De orchestrator is een Node.js service die elke 60 seconden:

Pending dashboard-approvals verstuurt (status=approve_requested)
Bulk-mail campagnes verwerkt (rate-limited per uur)
IMAP polled voor alle actieve mailboxen
Nieuwe mails classificeert via OpenAI (gpt-4o-mini)
FAQ matched op trigger-keywords → kant-en-klare reply
Vragen logt in questions_log voor self-learning
Auto-reply verstuurt (na 4 loop-checks) of escaleert naar Telegram

File: /home/ubuntu/mailplatform/orchestrator/orchestrator.js

Systemd: /etc/systemd/system/mailplatform-orchestrator.service

Env: /etc/mailplatform/.env

Auto-reply loop-prevention

4 checks om mail-loops te voorkomen:

Subject begint met "Re: Re:" → skip (te diep)
From-adres == eigen mailbox → skip (self-loop)
From-adres staat in opt_outs → skip
AI concept_reply is leeg of trigger == auto_reply/bounce/spam → skip

6. Dashboard

Vanilla JS SPA met Pocketbase SDK. Tabs:

Overzicht — vandaag-stats + recente events
Live Events — realtime websocket-feed van alle email-events
Mailboxes — 1 card per mailbox met agent-info + events-vandaag
Agents — AI-config per mailbox
Vragen — questions_log; FAQ-suggesties als vraag ≥3× zonder match
Campagnes — bulk-mail lists + campagnes + rate-limit
Opt-outs — afgemelde adressen

7. Bulk-mail campagnes

Workflow:

Maak email-lijst (Campagnes tab → + Nieuwe lijst)
Importeer CSV: email,name,company per regel, header optioneel
Maak campagne: kies lijst + mailbox, schrijf subject/body met {{name}}, {{email}}, {{company}} placeholders, zet rate (default 25/uur)
Klik Start → orchestrator pikt elke minuut tot rate-limit bereikt

Bv: 500 leads, 25/uur = 20 uur doorlooptijd. Opt-outs worden automatisch geskipt. Bounces → status=failed, geen retry.

Programmatic campagne aanmaken

// node script
const pb = new PocketBase('https://mail.vindlokaal.eu');
await pb.collection('_superusers').authWithPassword(...);
const list = await pb.collection('email_lists').create({name, domain, description});
for (const email of leads) {
  await pb.collection('list_members').create({list: list.id, email, name, status: 'active'});
}
const camp = await pb.collection('campaigns').create({
  name, list: list.id, mailbox: mbId,
  subject: 'Hoi {{name}}', body_html: '<p>...</p>',
  rate_per_hour: 25, status: 'draft', total_recipients: leads.length,
});
// Dan campaign_recipients records aanmaken + status='running' zetten

8. FAQ & self-learning

faq_templates collection bevat kant-en-klare antwoorden:

code — unieke identifier (bv "claim_pagina")
triggers — JSON array met keywords (bv ["claim", "claimen"])
subject, body_html — template (mag {{name}} bevatten)
help_url — link naar handleiding-pagina
domain — beperkt tot 1 domein, of leeg = alle
use_count — counter (wordt opgehoogd bij match)

Self-learning: elke mail wordt geanalyseerd door OpenAI, krijgt een topic-label (bv "vragen over claim-proces"). Per topic+mailbox combinatie wordt counter opgehoogd in questions_log. Bij count ≥ 3 zonder FAQ-match → suggested_for_faq=true → dashboard toont "⚠️ Maak FAQ?" badge.

Handleiding-pagina's: /var/www/dashboard/help/ met screenshots in /var/www/dashboard/help-images/.

9. Nieuw domein toevoegen

Volledig geautomatiseerd via één script:

node /home/jojo/mailplatform/scripts/add-domain.cjs \
  <domain> <brand> <accent_hex> <grad1> <grad2> "<tagline>"

# Voorbeeld:
node add-domain.cjs simpelscherm.nl Simpelscherm "#9b59b6" "#9b59b6" "#8e44ad" \
  "Het simpele digitale infoscherm voor jouw bedrijf"

Dit doet automatisch:

Resend: domain aanmaken + DNS records ophalen
OVH: MX + SPF + DKIM + DMARC records toevoegen
Postfix: domain + info@ mailbox aanmaken in SQLite (random pw)
Pocketbase: domain + mailbox + agent records aanmaken
Resend verify triggeren

Vereiste: domein moet in OVH-zones staan. Voor andere registrars: DNS handmatig. Mailbox-wachtwoord toevoegen aan /home/jojo/.credentials/mail-users.json. Theme toevoegen in orchestrator.js (functie wrapEmailHtml, themes-map).

10. Troubleshooting

Orchestrator stuurt niet

ssh vindlokaal-mail 'sudo systemctl status mailplatform-orchestrator'
ssh vindlokaal-mail 'sudo journalctl -u mailplatform-orchestrator -n 50 --no-pager'

Mails komen niet binnen

ssh vindlokaal-mail 'sudo tail -50 /var/log/mail.log'
# check Postfix queue:
ssh vindlokaal-mail 'sudo mailq'

Dashboard laadt niets

Check Pocketbase + nginx HTTP/1.1 setting (zie hierboven). Browser console → check websocket connection.

Resend webhook werkt niet

# Test endpoint:
curl https://mail.vindlokaal.eu/webhook/health
# Bekijk dashboard.resend.com → Webhooks → Recent deliveries

11. Backup & recovery

Belangrijk om te backuppen:

Wat	Locatie op VPS
Pocketbase database	`/home/ubuntu/pocketbase/pb_data/`
Postfix mailusers SQLite	`/etc/postfix/sqlite/mailusers.db`
Mailboxes (vmail)	`/var/vmail/`
Postfix config	`/etc/postfix/`
Dovecot config	`/etc/dovecot/`
Nginx vhost	`/etc/nginx/sites-enabled/mail.vindlokaal.eu`
Orchestrator code	`/home/ubuntu/mailplatform/`
Dashboard	`/var/www/dashboard/`
Let's Encrypt certs	`/etc/letsencrypt/`

Snapshot suggestie: OVH snapshot dagelijks via control panel, of rsync naar Jojo-server:

rsync -avz vindlokaal-mail:/home/ubuntu/pocketbase/pb_data/ \
  /home/jojo/backups/mailplatform/pb_data-$(date +%Y%m%d)/

12.
🔌 Complete API docs: marketing.vindlokaal.eu/docs/api.html

12.
✅ Checklist nieuw platform: stappenplan voor toevoegen van een platform

12. Updates juni 2026 — wat is er bijgekomen

Nieuwe features die het mail-platform uitbreiden — niet uitgebreid hier gedocumenteerd, alleen kort vermeld zodat je weet dat ze bestaan. Volledige uitleg: zie /marketing.vindlokaal.eu/docs/.

12.1 Marketing-hub gekoppeld

Apart subdomein marketing.vindlokaal.eu draait nu naast mail-platform. Bevat: funnels (drip campaigns), templates-library, kennisbank met semantic search, categorie-regels, learning queue. Deelt zelfde Pocketbase-database — wijzigingen werken direct door in mail-orchestrator.

12.2 Kennisbank v2 (semantic search)

Naast de oude knowledge_base (korte snippets) is er nu kb_documents + kb_chunks met OpenAI embeddings. Upload PDF/MD docs → automatisch gechunkt + embed. AI zoekt semantisch (niet alleen keywords). Per doc scope: internal / customer_facing / both. Mail-orchestrator gebruikt deze via marketing-hub /api/v1/ask.

12.3 Categorie-regels per platform

Per (platform, categorie) bepaal je: welke docs AI mag raadplegen, strictness (STRICT_DOCS / SOEPEL_DOCS / ALTIJD_ESCALATE / AUTO_RESPOND / AUTO_DELETE), min confidence. Defense-in-depth: bij klant-replies wordt internal docs automatisch geweigerd.

12.4 Zelflerend systeem

Bij elke ESCALATE → automatisch in learning_queue. Mens antwoordt vanuit dashboard. Met 1-klik "📌 Voeg toe aan KB" wordt vraag+antwoord aan kennisbank toegevoegd. AI weet het volgende keer.

12.5 Watchman controller

Systemd service die elke 5 min checkt op anomalieën (te veel escalaties, failed mails, bouncerate, engine-stall) en alerts stuurt via Telegram. Plus dagelijks 08:00 rapport met mail-volumes, conversies, OpenAI-kosten. Alerts gedupliceerd (zelfde alert max 1× per uur).

12.6 Inbox v2

Inbox-tab in dashboard heeft nu: KPI-cards bovenaan (Wacht op JOU / Door AI / Binnen vandaag), 3 tabjes (Wacht op JOU / Alles / Afgehandeld), urgent-mails krijgen rode rand + URGENT-badge, status-tooltips met uitleg, prominente "Reden"-blok bij failed/escalated mails, auto-refresh via websocket (geen F5 meer nodig).

12.7 Image uploads (templates + KB)

In marketing-hub template-editor en KB-doc-editor: knop "📷 Plak screenshot/image" → file picker → upload naar /var/www/marketing/uploads/ → image-tag automatisch ingevoegd. Bestanden publiek via https://marketing.vindlokaal.eu/uploads/..., max 5MB.

12.8 Facturen mailboxen

Naast info@ heeft elk domein nu ook facturen@ met eigen agent + facturatie-prompt (categorieën: factuur_kwijt, betalingstermijn, bedrag_klopt_niet, etc.). 13 mailboxen totaal.

12.9 todlertube.com toegevoegd

7e platform: TodlerTube — veilig videoplatform voor toddlers. Roze branding-theme.

12.10 Billing-hub gemigreerd

Parallel op billing.vindlokaal.eu — eigen Postgres + cookie-login + p-queue (anti-crash). Pollers nog op Jojo tot user "cutover" zegt.

Voor vragen / aanpassingen: zie source in /home/ubuntu/mailplatform/ op de VPS, of /home/jojo/mailplatform/scripts/ lokaal.