E-Mail-Anhänge automatisch verarbeiten

Eingehende E-Mails enthalten häufig Dokumente als Anhänge – Bilder, PDFs, manchmal verschachtelte .eml- oder .msg-Dateien. In unserer Kanzlei konnte eine einzelne Mandanten-E-Mail ein Dutzend Fotos eines Unfallberichts, ein PDF-Gutachten und eine weitergeleitete E-Mail mit eigenen Anhängen enthalten. Eine E-Mail-Anhang-Verarbeitungs-API, die jeden Anhang extrahiert, validiert und in die richtige Pipeline leitet, würde stundenlange manuelle Arbeit einsparen.

Bilder müssen zur Dokumentextraktion oder OCR, PDFs zum Zusammenführen oder Komprimieren weitergeleitet werden – und verschachtelte E-Mails müssen rekursiv verarbeitet werden.

Warum eine eigene E-Mail-Anhang-Verarbeitungslösung Wochen dauert

Wer das selbst aufbauen möchte, stellt schnell fest, dass das Parsen von .eml und .msg mail-parser, extract-msg oder Ähnliches erfordert. Dann müssen MIME dekodiert, verschachtelte Nachrichten verarbeitet, Binärdaten extrahiert, Formate erkannt (magika, Dateisignaturen), auf Viren geprüft und nach Bild-/PDF-Logik verzweigt werden. Jeder Schritt birgt eigene Fehlerquellen: fehlerhafte Header, Kodierungen und verschachtelte E-Mails mit eigenen Anhängen. Eine robuste E-Mail-Anhang-Verarbeitungs-API intern aufzubauen dauert Wochen.

Wie die MaraDocs E-Mail-Anhang-Verarbeitungs-API das in Minuten löst

Die MaraDocs API validiert .eml- und .msg-Dateien in einem einzigen Aufruf. Man erhält strukturierte Anhang-Handles – jeweils mit Typinformation. Von dort aus kann nach Bild- oder PDF-Operationen verzweigt werden: nach Typ validieren, dann Dokumentextraktion, OCR, Komposition oder Komprimierung anwenden. Die API unterstützt rekursive Verarbeitung von E-Mails, die innerhalb von E-Mails angehängt sind.

Workflow zur E-Mail-Anhang-Verarbeitung: Hochladen, Validieren, Extrahieren, Weiterleiten

E-Mail-Datei hochladen, email.validate aufrufen. Die Antwort enthält Anhang-Handles – jeweils mit Inhaltstyp und Metadaten. Für jeden Anhang den Typ prüfen (Bild, PDF oder verschachtelte E-Mail). Den Anhang mit img.validate oder pdf.validate validieren, dann in die Pipeline verketten: flow.ocrImg für Bilder, pdf.compose zum Zusammenführen von PDFs, pdf.optimize zur Komprimierung. Verschachtelte E-Mails können erneut validiert werden, um deren Anhänge rekursiv zu extrahieren. Die gesamte Pipeline läuft serverseitig; Handles werden zwischen den Schritten übergeben, ohne herunterzuladen und erneut hochzuladen.

Was MaraDocs unterscheidet: Workspaces, Webview und deutsches Datenschutzrecht

Die meisten Dokumenten-APIs zwingen dazu, jeden Anhang herunterzuladen, anderswo erneut hochzuladen und Identitäten über mehrere Schritte hinweg zu verfolgen. Bei MaraDocs leben alle Dateien – die E-Mail und ihre Anhänge – im selben Workspace. E-Mail validieren, Anhang-Handles iterieren und an img/pdf/flow-Endpunkte übergeben. Handles fließen; Daten bleiben serverseitig. Keine Download-Hochlade-Zyklen für jeden Anhang.

Wenn eine verschachtelte E-Mail eine unerwartete Struktur aufweist oder ein Anhang manuell geprüft werden muss, kann app.maradocs.io mit dem Workspace-Secret geöffnet werden, um Dateien zu inspizieren und umzuordnen. Nutzer erhalten volle manuelle Kontrolle, wenn die Automatisierung an ihre Grenzen stößt.

Die Verarbeitung erfolgt in Deutschland (Maramia GmbH), mit Verschlüsselung im Ruhezustand und während der Übertragung. Workspaces verfallen nach 7 Tagen. Keine Daten verlassen die EU. Für datenschutzsensible E-Mail-Verarbeitung ist das relevant.

TypeScript-Code zum Extrahieren von E-Mail-Anhängen

API-Referenz: data/upload, email/validate, img/validate, pdf/validate, flow.ocrImg, data/download/pdf

import { MaraDocsClient } from "@maramia/maradocs-sdk-ts";
import { okEmail } from "@maramia/maradocs-sdk-ts/models/email";
import { okImg } from "@maramia/maradocs-sdk-ts/models/img";
import { okPdf } from "@maramia/maradocs-sdk-ts/models/pdf";

const client = new MaraDocsClient({ workspaceSecret: workspace_secret });

// E-Mail hochladen und validieren
const uploaded = await client.data.upload(emailFile);
const validated = await client.email.validate({
  unvalidated_file_handle: uploaded.unvalidated_file_handle,
});
const email = okEmail(validated);

const pdfHandles: string[] = [];
for (const att of email.attachments) {
  if (att.content_type?.startsWith("image/")) {
    const imgVal = await client.img.validate({
      unvalidated_file_handle: att.unvalidated_file_handle,
    });
    const imgHandle = okImg(imgVal);
    const pdfHandle = await client.flow.ocrImgHandle(imgHandle);
    pdfHandles.push(pdfHandle);
  } else if (att.content_type === "application/pdf") {
    const pdfVal = await client.pdf.validate({
      unvalidated_file_handle: att.unvalidated_file_handle,
    });
    pdfHandles.push(okPdf(pdfVal));
  }
}
// Zusammenführen und herunterladen
const composed = await client.pdf.compose({
  pdfs: pdfHandles.map((pdf_handle) => ({ pdf_handle })),
});
const blob = await client.data.downloadPdf({ pdf_handle: composed.pdf_handle });

Python-Code zur E-Mail-Anhang-Extraktion

API-Referenz: data/upload, email/validate, img/validate, pdf/validate, pdf/compose, data/download/pdf

# pip install python-decouple requests
"""Extract PDF attachments from an email using MaraDocs. Set ACCOUNT_SECRET in .env or environment."""

import sys
import time
from pathlib import Path

import requests
from decouple import config

API_URL = "https://api.maradocs.io/v1"


def create_workspace() -> dict:
    """Create a workspace and return auth headers."""
    r = requests.post(
        f"{API_URL}/workspace",
        headers={"Authorization": f"Bearer {config('ACCOUNT_SECRET')}"},
        json={"subaccount": None},
    )
    ws = r.json()
    return {"Authorization": f"Bearer {ws['workspace_secret']}"}


def upload_file(path: Path, auth: dict) -> dict:
    """Upload a file via two-step flow (signed URL + S3 POST). Returns unvalidated_file_handle."""
    data = path.read_bytes()
    resp = requests.post(
        f"{API_URL}/data/upload",
        headers={**auth, "Content-Type": "application/json"},
        json={"name": path.name, "size": len(data)},
    ).json()
    requests.post(
        resp["post_url"],
        data=resp.get("post_header", {}),
        files={"file": (path.name, data, "message/rfc822")},
    )
    return resp["unvalidated_file_handle"]


def run_job(path: str, payload: dict, auth: dict, timeout: int = 60) -> dict:
    """Run a job and poll until complete. Returns the result (unwraps response if present)."""
    url = f"{API_URL}/{path}"
    r = requests.post(url, headers=auth, json=payload).json()
    job_id = r["job_id"]
    start = time.time()
    while time.time() - start < timeout:
        poll_r = requests.get(f"{url}/{job_id}", headers=auth)
        if poll_r.status_code == 200:
            return poll_r.json()
    raise TimeoutError(f"Job {path} timed out")


def pdf_handles_from_email(email_handle: dict) -> list:
    """Recursively extract all pdf_handles from an email_handle (handles nested emails)."""
    handles = []
    for att in email_handle.get("attachments", []):
        media = att.get("media_type") or {}
        mt = media.get("media_type", "") if isinstance(media, dict) else ""
        validated = att.get("validated") or {}

        if mt == "application/pdf":
            resp = validated.get("response", {})
            if pdf_h := resp.get("pdf_handle"):
                handles.append(pdf_h)
        elif mt == "message/rfc822":
            nested = (validated.get("response") or {}).get("email_handle")
            if nested:
                handles.extend(pdf_handles_from_email(nested))
    return handles


def download_pdf(pdf_handle: str, auth: dict) -> bytes:
    """Request signed URL and fetch PDF bytes."""
    r = requests.post(
        f"{API_URL}/data/download/pdf",
        headers=auth,
        json={"pdf_handle": pdf_handle},
    )
    info = r.json()
    dl = requests.get(info["url"], headers=info.get("headers", {}))
    return dl.content


def main() -> None:
    email_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("input_email.eml")
    auth = create_workspace()
    handle = upload_file(email_path, auth)
    email_data = run_job("email/validate", {"unvalidated_file_handle": handle}, auth)
    email_handle = email_data["response"]["email_handle"]
    pdf_handles = pdf_handles_from_email(email_handle)

    if not pdf_handles:
        sys.exit("No PDF attachments found")

    composed = run_job(
        "pdf/compose",
        {"pdfs": [{"pdf_handle": h} for h in pdf_handles]},
        auth,
    )
    pdf_handle = composed["pdf_handle"]
    Path("attachments.pdf").write_bytes(download_pdf(pdf_handle, auth))
    print("attachments.pdf created")


if __name__ == "__main__":
    main()

Zusammenfassung und nächste Schritte

Eine E-Mail-Anhang-Verarbeitungs-API, die Anhänge extrahiert, validiert und weiterleitet, ist verfügbar. MaraDocs übernimmt Virenscan, Formaterkennung und rekursives E-Mail-Parsing. Für vollständige Automatisierung kombinieren mit Dokumentenscanner, PDF-Verarbeitung und Texterkennung.

---

Jetzt ausprobieren: MaraDocs API | TypeScript SDK

---