Overview

Mailing

Email sending from the WUIC backend: scheduled distribution lists, event-driven workflow emails and system emails (user registration). All channels use the same SMTP configured in AppSettings.

SMTP configuration (appsettings.json → AppSettings)

KeyMeaning
email-host / email-port / email-sslSMTP server, port (25, 465, 587) and TLS
email-user / email-pwdcredentials; with an empty email-user the process identity is used
email-sender-address-mailing / email-sender-name-mailingsender and display name of distribution lists and workflow emails
email-sender-address-registration / email-admin-registrationsender of registration emails and recipient of admin notifications
content-urlbase URL for confirmation links inside emails

Keys are hot-reloaded. Multi-tenant: every key accepts a per-company override in the form <key>__a<aziendaId> (e.g. email-host__a1), falling back to the global value. The package template uses the placeholder __SET_SMTP_PASSWORD__: as long as it stays, SMTP is considered not configured and workflow emails remain in the logged state.

Distribution lists (scheduler)

Lists live in the metadata DB:

  • _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 accepts single_per_recipient (one message per recipient, default), single_to_all (one message with every recipient in To) and single_to_bcc (one message with everyone in Bcc).

Sending is a scheduler task with action_type = 4 and action_cmd = <list id>. In the task's params_values you can override subject, body, isHtml, from, fromName (key=value pairs). With single_run = 1 the list is disabled after the first successful send. Tables, routes and entries in the Administration menu come with scripts/scaffold-scheduler-mailing-metadata.sql (tables only with scripts/add-mailing-tables.sql). Frequency, retries and execution log: see Scheduling.

Emails from workflows (outbox)

The internal action of type 101 (Email) of the workflow designer calls MetaService.enqueueWorkflowEmail: the mail is inserted into _wuic_mail_outbox (mail_to, subject, body, related_route, related_pk, status, error, sent_at) and, when SMTP is configured, sent immediately with status = sent; otherwise it stays logged (useful in demos and environments without SMTP). A send failure produces status = error with the message in error. Multiple recipients are separated by ; or ,.

Recipients, subject and body are decided by the server, not by the browser. The Email node of the saved graph has an emailConfig (route, to, subject, body; right-click on the node → Configure email) with record fields in double braces, e.g. {{fornitore_email}}. The callback sends only the node and the record, together with the context of the current workflow:

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

The server checks that the screen's route belongs to the saved graph and is readable by the caller, and that the node is reachable from an action the caller can run. It reads the record with the caller's permissions (workflow bundle rules and row restrictions included) and ignores mail_to, subject and body sent by the client. Non-superadmins keep the limits of 10 recipients per call and 60 every 10 minutes (recipients are counted). Otherwise 403/429 errors.auth.operation_disabled with a reason, for example 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. nodeId is required when the graph has more than one email node (configured or not): without it, 403 email_node_not_found. An email node without emailConfig is refused to everyone, superadmins included. Dates and booleans of record fields are written in the server culture (short date, time only when it is not midnight; Yes/No). Only a superadmin can still send free recipients and text: without nodeId and with to (wtoolbox.enqueueEmail({ to, subject, body })), also inside a workflow; for other users to, subject and body do not count.

System emails

User registration, activation and the notification to the administrator use email-sender-address-registration and email-admin-registration. See Authentication & Authorization.

Troubleshooting

  • SMTP host is required / From address is required: email-host or email-sender-address-mailing empty.
  • No recipients configured for mailing list: no recipient with enabled = 1.
  • Mailing list N not found, disabled or deleted: wrong action_cmd or list disabled (also by single_run).
  • Workflow emails always logged: password still __SET_SMTP_PASSWORD__ or empty host.