Overview

Mailing

Invio email dal backend WUIC: liste di distribuzione schedulate, email event-driven dei workflow ed email di sistema (registrazione utenti). Tutti i canali usano lo stesso SMTP configurato in AppSettings.

Configurazione SMTP (appsettings.json → AppSettings)

ChiaveSignificato
email-host / email-port / email-sslserver SMTP, porta (25, 465, 587) e TLS
email-user / email-pwdcredenziali; con email-user vuoto viene usata l'identita' del processo
email-sender-address-mailing / email-sender-name-mailingmittente e display name delle liste di distribuzione e delle email workflow
email-sender-address-registration / email-admin-registrationmittente delle email di registrazione e destinatario delle notifiche admin
content-urlURL base per i link di conferma nelle email

Le chiavi sono hot-reload. Multi-tenant: ogni chiave accetta un override per azienda nel formato <chiave>__a<aziendaId> (es. email-host__a1), con fallback al valore globale. Il template dei pacchetti usa il placeholder __SET_SMTP_PASSWORD__: finche' resta, l'SMTP e' considerato non configurato e le email workflow restano in stato logged.

Liste di distribuzione (scheduler)

Le liste vivono nel DB metadata:

  • _mailing_lists: list_name, enabled, single_run, subject_template, body_template, is_body_html, send_mode, notes, metadata_json
  • _mail_recipients: mailing_list_id, email, display_name, enabled, sort_order

send_mode accetta single_per_recipient (un messaggio per destinatario, default), single_to_all (un messaggio con tutti i destinatari in To) e single_to_bcc (un messaggio con tutti in Bcc).

L'invio e' un task dello scheduler con action_type = 4 e action_cmd = <id della lista>. In params_values del task si possono sovrascrivere subject, body, isHtml, from, fromName (coppie chiave=valore). Con single_run = 1 la lista viene disabilitata dopo il primo invio riuscito. Tabelle, route e voci nel menu Amministrazione arrivano con scripts/scaffold-scheduler-mailing-metadata.sql (le sole tabelle con scripts/add-mailing-tables.sql). Frequenza, retry e log di esecuzione: vedi Scheduling.

Email dai workflow (outbox)

L'azione interna di tipo 101 (Email) del workflow designer chiama MetaService.enqueueWorkflowEmail: la mail viene inserita in _wuic_mail_outbox (mail_to, subject, body, related_route, related_pk, status, error, sent_at) e, se l'SMTP e' configurato, inviata subito con status = sent; altrimenti resta logged (utile in demo e in ambienti senza SMTP). Un errore di invio produce status = error con il messaggio in error. Piu' destinatari si separano con ; o ,.

Destinatari, oggetto e testo li decide il server, non il browser. Il nodo Email del grafo salvato ha una emailConfig (route, to, subject, body; tasto destro sul nodo → Configura email) con i campi del record tra doppie graffe, es. {{fornitore_email}}. Il callback manda solo il nodo e il record, insieme al contesto del workflow corrente:

Snippet 1js
await wtoolbox.enqueueEmail({ nodeId: 'i_email', relatedRoute: 'wf_ap_esiti', relatedPk: row.id });

Il server verifica che la route della schermata sia del grafo salvato e leggibile dal chiamante, che il nodo sia raggiungibile da un'azione che il chiamante puo' eseguire, legge il record con i permessi del chiamante (regole del bundle del workflow e restrizioni di riga comprese) e ignora mail_to, subject e body mandati dal client. Per chi non e' superadmin restano i limiti di 10 destinatari per chiamata e 60 ogni 10 minuti (conta i destinatari). Altrimenti 403/429 errors.auth.operation_disabled con reason, ad esempio no_workflow_context, route_not_in_workflow, route_not_readable, email_node_not_found, email_node_not_allowed, related_record_not_readable, invalid_recipients, too_many_recipients, rate_limited. Il nodeId e' obbligatorio quando il grafo ha piu' di un nodo email (configurato o no): senza, 403 email_node_not_found. Un nodo email senza emailConfig viene rifiutato a tutti, superadmin compreso. Date e booleani dei campi del record si scrivono nella cultura del server (data breve, ora solo se diversa da mezzanotte; Sì/No). Solo il superadmin puo' ancora inviare destinatari e testo liberi: senza nodeId e con to (wtoolbox.enqueueEmail({ to, subject, body })), anche dentro un workflow; per gli altri utenti to, subject e body non contano.

Email di sistema

Registrazione utenti, attivazione e notifica all'amministratore usano email-sender-address-registration e email-admin-registration. Vedi Autenticazione & Autorizzazioni.

Troubleshooting

  • SMTP host is required / From address is required: email-host o email-sender-address-mailing vuoti.
  • No recipients configured for mailing list: nessun destinatario con enabled = 1.
  • Mailing list N not found, disabled or deleted: action_cmd errato oppure lista disabilitata (anche da single_run).
  • Email workflow sempre logged: password ancora __SET_SMTP_PASSWORD__ o host vuoto.