Routing e-mail + Worker: elabora le e-mail in modo programmatico all'edge

La maggior parte dei tutorial sul routing della posta elettronica di Cloudflare mostrano come inoltrare contato@seudominio.com a Gmail. Questo risolve il caso d’uso più semplice, ma nasconde la parte più interessante del servizio. Quando indirizzi un'e-mail a un Worker anziché a un indirizzo di destinazione, l'e-mail diventa dati: leggi il mittente, l'oggetto, le intestazioni, l'intero corpo e decidi cosa fare con tutto ciò all'interno di una funzione JavaScript in esecuzione all'edge. Ciò cambia in modo significativo ciò che è fattibile costruire senza la propria infrastruttura di posta elettronica.

Il gestore della posta elettronica e ciò che ricevi

La struttura di base di un lavoratore di posta elettronica utilizza un'esportazione denominata email all'interno dell'oggetto predefinito:

export default {
  async email(message, env, ctx) {
    // message.from — endereço do remetente
    // message.to  — endereço de destino no seu domínio
    // message.headers — objeto Headers com todos os cabeçalhos RFC 2822
    // message.raw — ReadableStream com a mensagem completa
  }
}

message.from e message.to sono stringhe con indirizzi. message.headers è un oggetto standard Web API Headers: accedi a message.headers.get('subject') o message.headers.get('x-mailer') nello stesso modo in cui faresti in un gestore di recupero. message.raw è un ReadableStream con l'intero messaggio RFC 2822, incluse intestazioni e corpo, con supporto per messaggi fino a 25 MB.

Sono disponibili quattro azioni: message.forward(address) per inoltrare a un indirizzo verificato, message.reply(response) per rispondere, message.setReject(reason) per rifiutare il messaggio con un messaggio di errore o semplicemente tornare senza chiamare nessuno, scartando silenziosamente il messaggio. Puoi combinare: filtrare per mittente, inoltrarne alcuni, rifiutarne altri ed elaborare il resto.

Il gap nell'analisi MIME

Ecco il punto menzionato discretamente dalla documentazione: non esiste un parser MIME integrato. message.raw ti dà il flusso grezzo. Se desideri estrarre l'oggetto con la codifica UTF-8, il corpo in testo semplice, l'HTML alternativo o gli allegati, devi analizzare tu stesso il MIME o utilizzare una libreria.

postal-mime funziona bene nell'ambiente Lavoratori. L'impostazione predefinita è consumare lo stream, convertirlo in ArrayBuffer e passarlo al parser:

import PostalMime from 'postal-mime';

const raw = await new Response(message.raw).arrayBuffer();
const parsed = await new PostalMime().parse(raw);

// parsed.subject, parsed.text, parsed.html, parsed.attachments

parsed.attachments è un array di oggetti con filename, mimeType e content (ArrayBuffer). Puoi salvare il contenuto in un bucket R2, estrarre metadati da un NF-e in XML o passare un PDF a un'API di estrazione. Il runtime Workers lo supporta senza alcuna configurazione aggiuntiva oltre all'importazione della libreria.

Il costo per consumare l'intero flusso è la memoria. Per i messaggi con allegati di grandi dimensioni vicini al limite di 25 MB, stai caricando tutto nella memoria del Worker. Nella maggior parte dei casi questo non costituisce un problema, ma nelle condutture ad alto volume vale la pena monitorarlo.

Modelli che ha senso costruire qui

Creazione automatica di ticket di supporto. L'e-mail arriva, estrai il mittente, l'oggetto e il corpo, assembli un payload e lo PUBBLICA sull'API Linear, Zendesk, Notion o su qualsiasi strumento utilizzato dal tuo team. Il ticket ora viene visualizzato con il contesto completo senza che nessuno debba copiarlo e incollarlo. Per i team che ricevono richieste via email ma lavorano con strumenti di tracciamento dei problemi, ciò elimina un passaggio manuale costante.

Acquisizione di fatture e documenti fiscali. Crei un indirizzo dedicato — nfe@seudominio.com — e qualsiasi fornitore che invia NF-e via email avrà l'allegato XML o PDF elaborato automaticamente: metadati estratti, file salvato in R2, record creato in D1. Il lavoratore fa quello che farebbe un essere umano, ma senza dover aprire l'e-mail.

Filtraggio prima dell'inoltro. Con la funzione catch-all attiva, *@seudominio.com cattura lo spam inviato a indirizzi casuali sul tuo dominio. Un lavoratore può confrontare il mittente con un elenco di domini problematici noti archiviati nel KV, verificare se l'oggetto contiene modelli tipici di spam e chiamare il numero message.setReject('spam detectado') prima di inoltrarlo alla tua casella di posta. Non è un filtro antispam completo, ma riduce il rumore senza costi aggiuntivi.

Avvisi e notifiche riformattati. Strumenti di monitoraggio (Grafana, PagerDuty, strumenti CI) inviano avvisi e-mail in formati che non sono sempre leggibili su un telefono. Un lavoratore intercetta queste e-mail, estrae le informazioni rilevanti dal corpo e pubblica un messaggio formattato su un canale Slack o Discord tramite webhook. L'e-mail originale può essere eliminata o inoltrata come archivio.

Cosa non funziona come pensi

message.reply() esiste e funziona, ma la risposta viene da noreply@cloudflare.com. Se desideri che il destinatario riceva una risposta automatica che sembra provenire da suporte@seudominio.com, il lavoratore deve chiamare un servizio SMTP in uscita — Resend, Mailgun, SES — passando le intestazioni necessarie. Il routing della posta elettronica non ha accesso al flusso in uscita del tuo dominio.

Se il lavoratore lancia un'eccezione non rilevata, l'e-mail viene rifiutata con errore 500. Non è previsto un nuovo tentativo automatico, né esiste una coda di messaggi non recapitabili. Qualsiasi logica che potrebbe fallire necessita di try/catch con fallback esplicito, in genere un message.forward() a un indirizzo di triage manuale quando qualcosa va storto durante l'elaborazione. Scoprire questo comportamento in produzione, con le email dei clienti rifiutate, è un'esperienza spiacevole.

Dove ha senso andare oltre l'inoltro?

Se Email Routing per te è solo un alias di Gmail, non toccherai mai Workers e non ne avrai bisogno. Ma se il tuo team utilizza già Workers per altri scopi (API, cron job, integrazioni), Email Worker si inserisce nella stessa infrastruttura con gli stessi collegamenti KV, D1, R2 e servizi esterni. Non stai aggiungendo un nuovo pezzo alla pila; stai aggiungendo un tipo di trigger a un ambiente già esistente.