# Mail2FaxBlock - STARFACE Custom Block

Ein Custom Block für den STARFACE Module Designer, der E-Mails abruft und PDF-Anhänge als Fax versendet.

## Features

- **IMAP/POP3 Unterstützung** mit SSL/TLS
- **POP3**: E-Mails werden IMMER nach erfolgreichem Versand gelöscht (+ Tracking um Duplikate zu vermeiden)
- **IMAP**: E-Mails werden als gelesen markiert (optional löschen)
- **Retry-Logik**: Bei besetzter Leitung oder Fehler wird automatisch erneut versucht
- **Konfigurierbare Wiederholungen**: Anzahl und Wartezeit einstellbar
- **PIN-Schutz**: Optionale Sicherheits-PIN im E-Mail-Text erforderlich

## Kompatibilität

- STARFACE 8.x, 9.x, 10.x (Java 21)

## Dateien

```
v8-9-10/
├── Mail2FaxBlock.java    # Quellcode des Custom Blocks
├── build-block.sh        # Kompilier-Script
├── libs/starface/        # STARFACE API JARs
└── README.md
```

## Build

### 1. STARFACE APIs holen (falls noch nicht geschehen)

```bash
cd ..
./fetch-starface-libs.sh <starface-ip>
```

### 2. Block kompilieren

```bash
./build-block.sh
```

Ergebnis: `Mail2FaxBlock.class`

## Installation im Module Designer

### 1. Neues Modul erstellen
- STARFACE Admin → Module → Module Designer
- "Neues Modul erstellen"
- Name: "Mail2Fax"

### 2. Block hochladen
- Tab "Ressourcen"
- "Datei hochladen" → `Mail2FaxBlock.class`

### 3. Funktion erstellen
- Tab "Funktionen"
- Neue Funktion erstellen
- Den hochgeladenen Block als Implementierung auswählen

### 4. Eingabe-Variablen konfigurieren

| Variable | Typ | Beschreibung | Default |
|----------|-----|--------------|---------|
| mailServer | STRING | IMAP/POP3 Server | |
| mailPort | NUMBER | Port | 993 |
| mailProtocol | STRING | "IMAP" oder "POP3" | IMAP |
| mailUsername | STRING | E-Mail Benutzer | |
| mailPassword | STRING | E-Mail Passwort | |
| mailUseSsl | BOOLEAN | SSL aktivieren | true |
| mailFolder | STRING | Ordner | INBOX |
| deleteAfterProcess | BOOLEAN | E-Mails löschen (nur IMAP) | false |
| faxAccountId | STARFACE_USER | Fax-Benutzer (Dropdown) | |
| faxSenderNumber | STRING | Absender-Faxnummer | |
| authorizedSenders | STRING | Erlaubte Absender (optional) | |
| pin | STRING | Sicherheits-PIN (optional) | |
| maxRetries | NUMBER | Max. Wiederholungsversuche | 3 |
| retryDelayMinutes | NUMBER | Minuten zwischen Versuchen | 5 |

### 5. Timer konfigurieren

Der Block muss regelmäßig ausgeführt werden um E-Mails abzurufen. Dafür den Timer im Module Designer konfigurieren:

1. Tab **"Timer"** öffnen
2. Auf **[+]** klicken um einen neuen Schedule hinzuzufügen
3. Intervall festlegen (empfohlen: alle 60 Sekunden)

![Timer-Tab im Module Designer](screenshots/timer-tab.png)

**Hinweis:** Der Block hat einen eingebauten Lock-Mechanismus. Wenn der Timer erneut auslöst während der Block noch läuft, wird die neue Ausführung automatisch übersprungen. Keine Gefahr von Duplikaten.

### 6. Modul aktivieren

## Benutzung

1. E-Mail an das konfigurierte Postfach senden
2. **Betreff** = Ziel-Faxnummer (z.B. `+49721123456`)
3. **Anhang** = PDF-Datei(en)
4. **E-Mail-Text** = PIN (falls konfiguriert)

Das Modul ruft regelmäßig E-Mails ab und sendet PDFs als Fax.

## PIN-Schutz

Wenn eine PIN konfiguriert ist, muss diese im E-Mail-Text enthalten sein, damit das Fax gesendet wird.

- **PIN nicht gesetzt**: Alle E-Mails werden verarbeitet (nur Absender-Prüfung falls konfiguriert)
- **PIN gesetzt**: Die PIN muss irgendwo im E-Mail-Text (plain text oder HTML) vorkommen
- **PIN nicht gefunden**: E-Mail wird als gelesen markiert, kein Fax gesendet, Log-Eintrag "PIN in Emailtext nicht vorhanden oder falsch"

## Output-Variablen

| Variable | Typ | Beschreibung |
|----------|-----|--------------|
| processedCount | NUMBER | Verarbeitete E-Mails |
| sentFaxCount | NUMBER | Gesendete Faxe |
| errorCount | NUMBER | Fehleranzahl |
| pendingRetries | NUMBER | Wartende Wiederholungsversuche |
| statusMessage | STRING | Status-Meldung |

## Retry-Verhalten

Bei folgenden Fehlern wird automatisch erneut versucht:
- Leitung besetzt
- Keine Antwort
- Übertragungsfehler

Die Retry-Daten werden gespeichert in:
- `/var/starface/module-data/mail2fax_retry.txt`

Nach Erreichen von `maxRetries` wird der Fax-Versuch verworfen.

## POP3-Tracking

Da POP3 keine "gelesen"-Flags unterstützt, speichert der Block verarbeitete Message-IDs in:
- `/var/starface/module-data/mail2fax_processed.txt`

So werden Duplikate vermieden, auch wenn E-Mails nicht sofort gelöscht werden können.