Elaborare automaticamente allegati email

Le email in arrivo contengono spesso documenti come allegati – immagini, PDF, a volte file .eml o .msg annidati. Nel nostro studio legale, una singola email di un cliente poteva contenere una dozzina di foto di un rapporto di incidente, una perizia in PDF e un'email inoltrata con i propri allegati. Un'API di elaborazione allegati email che estraesse, validasse e indirizzasse ogni allegato alla pipeline corretta avrebbe fatto risparmiare ore di lavoro manuale.

Le immagini devono essere inoltrate all'estrazione documenti o all'OCR, i PDF alla fusione o compressione – e le email annidate devono essere elaborate in modo ricorsivo.

Perché una soluzione propria di elaborazione allegati email richiede settimane

Chi vuole sviluppare questo internamente scopre presto che il parsing di .eml e .msg richiede mail-parser, extract-msg o simili. Poi bisogna decodificare MIME, elaborare messaggi annidati, estrarre dati binari, riconoscere formati (magika, firme di file), controllare virus e indirizzare secondo la logica immagini/PDF. Ogni passaggio comporta proprie fonti di errore: header difettosi, codifiche ed email annidate con propri allegati. Costruire internamente un'API robusta di elaborazione allegati email richiede settimane.

Come l'API di elaborazione allegati email MaraDocs risolve questo in minuti

L'API MaraDocs valida file .eml e .msg in una singola chiamata. Si ottengono handle di allegati strutturati – ciascuno con informazioni sul tipo. Da lì si può procedere con operazioni su immagini o PDF: validare per tipo, poi applicare estrazione documenti, OCR, composizione o compressione. L'API supporta l'elaborazione ricorsiva di email allegate all'interno di email.

Workflow di elaborazione allegati email: Caricamento, Validazione, Estrazione, Inoltro

Caricare il file email, chiamare email.validate. La risposta contiene handle di allegati – ciascuno con tipo di contenuto e metadati. Per ogni allegato controllare il tipo (immagine, PDF o email annidata). Validare l'allegato con img.validate o pdf.validate, poi concatenare nella pipeline: flow.ocrImg per immagini, pdf.compose per unire PDF, pdf.optimize per la compressione. Le email annidate possono essere validate nuovamente per estrarre i loro allegati ricorsivamente. L'intera pipeline funziona lato server; gli handle vengono passati tra i passaggi, senza scaricare e ricaricare.

Cosa distingue MaraDocs: Workspace, Webview e normativa tedesca sulla privacy

La maggior parte delle API documenti costringe a scaricare ogni allegato, ricaricarlo altrove e tracciare le identità attraverso più passaggi. Con MaraDocs tutti i file – l'email e i suoi allegati – vivono nello stesso workspace. Validare l'email, iterare gli handle degli allegati e passarli agli endpoint img/pdf/flow. Gli handle fluiscono; i dati rimangono lato server. Nessun ciclo scarica-carica per ogni allegato.

Se un'email annidata ha una struttura inaspettata o un allegato deve essere controllato manualmente, si può aprire app.maradocs.io con il workspace secret per ispezionare e riorganizzare i file. Gli utenti ottengono pieno controllo manuale quando l'automazione raggiunge i suoi limiti.

L'elaborazione avviene in Germania (Maramia GmbH), con crittografia a riposo e in transito. I workspace scadono dopo 7 giorni. Nessun dato lascia l'UE. Per l'elaborazione di email sensibili alla privacy questo è rilevante.

Codice TypeScript per estrarre allegati email

Riferimento API: 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 });

// Caricare e validare email
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));
  }
}
// Unire e scaricare
const composed = await client.pdf.compose({
  pdfs: pdfHandles.map((pdf_handle) => ({ pdf_handle })),
});
const blob = await client.data.downloadPdf({ pdf_handle: composed.pdf_handle });

Codice Python per l'estrazione di allegati email

Riferimento API: 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()

Riepilogo e prossimi passi

È disponibile un'API di elaborazione allegati email che estrae, valida e inoltra gli allegati. MaraDocs si occupa di scansione virus, riconoscimento formato e parsing ricorsivo di email. Per un'automazione completa combinare con scanner documenti, elaborazione PDF e riconoscimento testo.

---

Prova ora: API MaraDocs | SDK TypeScript

---