ConvertMail 🚀

Automatisierte E-Mail-basierte Dateikonvertierung mit Multi-File-Support

ConvertMail ist ein intelligentes E-Mail-Automatisierungssystem, das Dateien über E-Mail-Anhänge empfängt, sie automatisch konvertiert und die Ergebnisse per E-Mail zurücksendet. Mit Support für mehrere Dateien gleichzeitig und intelligentem Chunking für große Ergebnisse.

✨ Features

🎯 Kern-Features

Multi-File-Support: Bis zu 10 Dateien gleichzeitig verarbeiten
Intelligentes Chunking: Automatische Aufteilung großer Ergebnisse auf mehrere E-Mails
Robust Error Handling: Detailliertes Fehler-Reporting und teilweise Erfolge
Dual SMTP Support: Mailcow für interne, Brevo für externe E-Mails
Echtzeit-Verarbeitung: IMAP IDLE für sofortige E-Mail-Erkennung

🔧 Technische Features

TypeScript: Vollständig typisiert für bessere Entwicklererfahrung
Modulare Architektur: Einfach erweiterbare Konvertierungsstrategien
Umfangreiche Validierung: Dateigröße, Format und Sicherheitsprüfungen
Professionelle Templates: HTML und Text E-Mail-Templates
Comprehensive Logging: Winston-basiertes Logging mit Rotation

🛡️ Sicherheit & Limits

Dateigröße-Limits (Standard: 50MB pro Datei)
Gesamtgröße-Limits (Standard: 50MB total)
Format-Whitelist für unterstützte Dateitypen
Domain-basierte Routing-Logik

🔄 Unterstützte Konvertierungen

🖼️ Bildkonvertierungen

Von	Nach	E-Mail-Adresse	Beschreibung
PNG	JPG	`convert+png-jpg@feuchte.org`	PNG zu JPG konvertieren
JPG	PNG	`convert+jpg-png@feuchte.org`	JPG zu PNG konvertieren
HEIC	JPG	`convert+heic-jpg@feuchte.org`	iPhone HEIC zu JPG

📄 PDF-Bearbeitung

Operation	E-Mail-Adresse	Beschreibung
PDF → DOCX	`convert+pdf-docx@feuchte.org`	PDF zu Word-Dokument
PDF → Text	`convert+pdf-txt@feuchte.org`	Text aus PDF extrahieren
PDF optimieren	`convert+pdf-optimize@feuchte.org`	PDF komprimieren/optimieren

🎵 Audio & Archive

Operation	E-Mail-Adresse	Beschreibung
WAV → MP3	`convert+wav-mp3@feuchte.org`	WAV zu MP3 konvertieren
ZIP entpacken	`convert+zip-unpack@feuchte.org`	ZIP-Archive entpacken

🔍 Texterkennung

Operation	E-Mail-Adresse	Beschreibung
OCR	`convert+ocr@feuchte.org`	Text aus Bildern/PDFs extrahieren

ℹ️ Hilfe

Operation	E-Mail-Adresse	Beschreibung
Hilfe	`convert+help@feuchte.org` oder `convert@feuchte.org`	Verfügbare Konvertierungen anzeigen

🚀 Installation

Voraussetzungen

Node.js ≥ 18.0.0
npm oder yarn
E-Mail-Server mit IMAP/SMTP Zugang
FFmpeg (für Audio-Konvertierung)
Tesseract (für OCR)

Systemabhängigkeiten installieren

Ubuntu/Debian

sudo apt update
sudo apt install ffmpeg tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng

macOS

brew install ffmpeg tesseract tesseract-lang

Windows

FFmpeg: Download
Tesseract: Download

Projekt einrichten

Repository klonen

git clone https://github.com/your-username/convertmail.git
cd convertmail

Dependencies installieren

npm install

Umgebungsvariablen konfigurieren

cp .env.example .env
# .env Datei bearbeiten (siehe Konfiguration)

TypeScript kompilieren

npm run build

Anwendung starten

npm start

⚙️ Konfiguration

Umgebungsvariablen

Erstelle eine .env Datei basierend auf .env.example:

# IMAP Konfiguration (E-Mail-Empfang)
IMAP_HOST=mail.feuchte.org
IMAP_PORT=993
IMAP_USER=convert@feuchte.org
IMAP_PASS=your_password
IMAP_TLS=true

# SMTP Konfiguration - Mailcow (Interne E-Mails)
MAILCOW_SMTP_HOST=mail.feuchte.org
MAILCOW_SMTP_PORT=587
MAILCOW_SMTP_USER=convert@feuchte.org
MAILCOW_SMTP_PASS=your_password
MAILCOW_SMTP_TLS=true

# SMTP Konfiguration - Brevo (Externe E-Mails)
BREVO_SMTP_HOST=smtp-relay.brevo.com
BREVO_SMTP_PORT=587
BREVO_SMTP_USER=your_brevo_user
BREVO_SMTP_PASS=your_brevo_api_key
BREVO_SMTP_TLS=true

# Anwendungseinstellungen
APP_NAME=ConvertMail
APP_VERSION=1.0.0
NODE_ENV=production
LOG_LEVEL=info
TEMP_DIR=./temp
LOG_DIR=./logs

# Verarbeitungslimits
MAX_FILE_SIZE=50MB
MAX_TOTAL_SIZE=50MB
MAX_FILE_COUNT=10
SUPPORTED_FORMATS=png,jpg,jpeg,pdf,zip,wav,mp3,heic

# OCR Einstellungen
TESSERACT_LANG=deu+eng

Konfigurationsoptionen

Datei-Limits

MAX_FILE_SIZE: Maximale Größe pro Datei (z.B. "50MB", "100MB")
MAX_TOTAL_SIZE: Maximale Gesamtgröße aller Dateien
MAX_FILE_COUNT: Maximale Anzahl Dateien pro E-Mail

Log-Level

error: Nur Fehler
warn: Warnungen und Fehler
info: Informationen, Warnungen und Fehler (Standard)
debug: Alle Log-Nachrichten

📧 Verwendung

Grundlegende Nutzung

E-Mail erstellen
Ziel-Adresse wählen (z.B. convert+png-jpg@feuchte.org)
Dateien anhängen (bis zu 10 Dateien)
E-Mail senden
Auf Antwort warten (automatische Verarbeitung)

Beispiele

Einzelne Datei konvertieren

An: convert+png-jpg@feuchte.org
Betreff: Bitte konvertieren
Anhang: mein-bild.png

Ergebnis: Sie erhalten mein-bild.jpg zurück

Mehrere Dateien konvertieren

An: convert+heic-jpg@feuchte.org
Betreff: iPhone Fotos konvertieren
Anhänge: IMG_001.heic, IMG_002.heic, IMG_003.heic

Ergebnis: Sie erhalten alle als JPG-Dateien zurück

OCR auf PDF anwenden

An: convert+ocr@feuchte.org
Betreff: Text extrahieren
Anhang: scan.pdf

Ergebnis: Sie erhalten eine TXT-Datei mit dem extrahierten Text

Smart Chunking

Bei großen Ergebnissen werden die konvertierten Dateien automatisch auf mehrere E-Mails aufgeteilt:

Conversion Complete (1/3): PNG-JPG - Ihre Anfrage
Conversion Complete (2/3): PNG-JPG - Ihre Anfrage  
Conversion Complete (3/3): PNG-JPG - Ihre Anfrage

🛠️ Entwicklung

Entwicklungsumgebung

# Development Mode mit Hot Reload
npm run dev

# Tests ausführen
npm test

# Code formatieren
npm run format

# Linting
npm run lint
npm run lint:fix

# Build für Produktion
npm run build

Projekt-Struktur

convertmail/
├── src/
│   ├── config/           # Konfigurationsdateien
│   │   └── environment.ts
│   ├── convert/          # Konvertierungsstrategien
│   ├── imap/             # IMAP E-Mail-Überwachung
│   │   ├── watcher.ts
│   │   └── mailProcessor.ts
│   ├── mail/             # E-Mail-Versand und Routing
│   │   ├── sender.ts
│   │   ├── router.ts
│   │   └── templates.ts
│   ├── types/            # TypeScript Type-Definitionen
│   │   └── index.ts
│   ├── utils/            # Utility-Funktionen
│   │   ├── fileUtils.ts
│   │   ├── logger.ts
│   │   └── errorHandler.ts
│   └── index.ts          # Hauptanwendung
├── dist/                 # Kompilierte JavaScript-Dateien
├── temp/                 # Temporäre Dateien
├── logs/                 # Log-Dateien
├── .env                  # Umgebungsvariablen
├── .env.example          # Umgebungsvariablen-Vorlage
├── package.json
├── tsconfig.json
└── README.md

Neue Konvertierung hinzufügen

Konvertierungsstrategie erstellen

// src/convert/strategies/newConverter.ts
import { ConversionStrategy } from '../../types';

export const newConverterStrategy: ConversionStrategy = {
  name: 'New Converter',
  description: 'Converts files from X to Y',
  supportedInputs: ['x'],
  outputFormat: 'y',
  convert: async (inputFile) => {
    // Konvertierungslogik hier
    return {
      success: true,
      outputFiles: [outputFile],
      processingTime: Date.now() - startTime
    };
  }
};

Routing-Regel hinzufügen

// src/mail/router.ts
{
  pattern: /convert\+x-y@/i,
  conversionType: 'x-y',
  description: 'Convert X to Y',
}

Type-Definition erweitern

// src/types/index.ts
export type ConversionType = 
  | 'png-jpg'
  | 'x-y'  // Neue Konvertierung hinzufügen
  | ...

Debugging

# Debug-Logs aktivieren
DEBUG=* npm run dev

# Nur SMTP-Debug
SMTP_DEBUG=true npm run dev

# Externe E-Mails überspringen
SKIP_EXTERNAL_MAIL_TEST=true npm run dev

🚢 Deployment

Docker Deployment

FROM node:18-alpine

WORKDIR /app

# System dependencies
RUN apk add --no-cache \
    ffmpeg \
    tesseract-ocr \
    tesseract-ocr-data-deu \
    tesseract-ocr-data-eng

# Install app dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy source
COPY . .
RUN npm run build

# Create necessary directories
RUN mkdir -p temp logs

EXPOSE 3000

CMD ["npm", "start"]

PM2 Deployment

# PM2 installieren
npm install -g pm2

# Anwendung starten
pm2 start ecosystem.config.js

# Status prüfen
pm2 status

# Logs anzeigen
pm2 logs convertmail

# Neu starten
pm2 restart convertmail

Systemd Service

# /etc/systemd/system/convertmail.service
[Unit]
Description=ConvertMail Service
After=network.target

[Service]
Type=simple
User=convertmail
WorkingDirectory=/opt/convertmail
ExecStart=/usr/bin/node dist/index.js
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Nginx Reverse Proxy

server {
    listen 80;
    server_name convertmail.feuchte.org;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

📚 API Reference

ConversionResult Interface

interface ConversionResult {
  success: boolean;
  outputFiles: ProcessedFile[];
  error?: string;
  processingTime: number;
}

ProcessedFile Interface

interface ProcessedFile {
  filename: string;
  originalName: string;
  path: string;
  size: number;
  mimeType: string;
  extension: string;
}

EmailMessage Interface

interface EmailMessage {
  messageId: string;
  from: string;
  to: string;
  subject: string;
  text?: string;
  html?: string;
  attachments: EmailAttachment[];
  date: Date;
}

🔧 Troubleshooting

Häufige Probleme

IMAP-Verbindung fehlgeschlagen

# Konfiguration prüfen
echo $IMAP_HOST $IMAP_PORT $IMAP_USER

# Verbindung testen
telnet $IMAP_HOST $IMAP_PORT

SMTP-Versand fehlgeschlagen

# SMTP-Debug aktivieren
SMTP_DEBUG=true npm start

# Mailcow-Logs prüfen
docker logs mailcowdockerized_postfix-mailcow_1

Dateikonvertierung fehlgeschlagen

# FFmpeg verfügbar?
ffmpeg -version

# Tesseract verfügbar?
tesseract --version

# Temp-Verzeichnis beschreibbar?
ls -la temp/

Out of Memory

# Node.js Memory erhöhen
node --max-old-space-size=4096 dist/index.js

# Oder in package.json
"start": "node --max-old-space-size=4096 dist/index.js"

Log-Analyse

# Error-Logs anzeigen
tail -f logs/error.log

# Alle Logs mit Filterung
tail -f logs/combined.log | grep "conversion"

# Logs nach Zeitraum
grep "2024-01-01" logs/combined.log

Performance-Monitoring

# Memory-Verwendung überwachen
ps aux | grep node

# Disk-Usage prüfen
du -sh temp/ logs/

# Netzwerk-Verbindungen
netstat -an | grep :993  # IMAP
netstat -an | grep :587  # SMTP

🤝 Beitrag leisten

Development Setup

Fork das Repository
Feature-Branch erstellen: git checkout -b feature/amazing-feature
Changes committen: git commit -m 'Add amazing feature'
Branch pushen: git push origin feature/amazing-feature
Pull Request erstellen

Code-Standards

TypeScript: Vollständige Typisierung
ESLint: Code-Quality sicherstellen
Prettier: Code-Formatierung
Conventional Commits: Commit-Messages standardisieren

Testing

# Unit Tests
npm test

# Integration Tests
npm run test:integration

# Test Coverage
npm run test:coverage

Dokumentation

Code-Kommentare in Deutsch oder Englisch
README bei neuen Features aktualisieren
JSDoc für öffentliche APIs

📄 Lizenz

Dieses Projekt ist unter der MIT License lizenziert.

MIT License

Copyright (c) 2024 Jack-Jean Feuchte

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 Danksagungen

ImapFlow für IMAP-Support
Nodemailer für SMTP-Funktionalität
Sharp für Bildverarbeitung
Tesseract.js für OCR
FFmpeg für Audio-/Video-Konvertierung

ConvertMail - Entwickelt mit ❤️ von Jack-Jean Feuchte

Fragen, Probleme oder Feedback? Issue erstellen oder E-Mail an convert+help@feuchte.org

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

dervonnebe/convertmail

Folders and files

Latest commit

History

Repository files navigation