Corsivo Mail

La pagina amministrativa usa tre aree del workspace Corsivo: Operatività (Coda, Log invii, Invia test, Stato), Configurazione (Invio, Coda e conservazione, Account SMTP, Gruppi destinatari, Moduli, Esporta / Importa) e Aspetto (Stile, Modelli, Footer). Le sezioni di Invio e Coda condividono il form originale: il cambio di pannello conserva i campi e i valori, mentre la validazione apre il pannello che contiene il primo errore. L'avviso del browser protegge le modifiche non salvate. URL, azioni POST e accesso agli editor nativi restano invariati; la Posta in arrivo usa il contenitore ampio senza una seconda sidebar.

assets/admin-workspace.css è una copia locale del foundation admin-workspace/style.css di wp-admin-ui; adattamenti e navigazione sono in admin-workspace-layout.css e admin-workspace.js. Non esistono dipendenze runtime da altri plugin. La shell PHP riusa i bundle React esistenti senza ricompilazione. Verifica DOM: node tests/workspace-navigation.cjs <percorso-al-modulo-jsdom>.

Infrastruttura email della suite Corsivo: coda di invio durevole, account SMTP multipli con credenziali cifrate, template Gutenberg, log operativo e trasporto condiviso per gli altri plugin della famiglia.

Scopo

WordPress spedisce email in modo sincrono, senza retry, senza storia e senza garanzie: se il trasporto fallisce durante una richiesta, il messaggio è perso. Corsivo Mail esiste per dare alla suite un unico punto di uscita affidabile: gli invii espliciti della suite e le chiamate wp_mail che soddisfano la policy di accodamento passano da una coda durevole con lease e retry, vengono inviate da un worker fuori dalla richiesta HTTP e lasciano una traccia consultabile. Allegati, embed, coda disattivata e bypass runtime restano sincroni. I plugin della suite (Bookings, Members, Newsletter) non parlano con SMTP: accodano qui e osservano l'esito.

Il plugin copre volutamente uno scope ampio: trasporto e coda, template email editabili a blocchi, automazioni, un modulo IMAP opzionale per leggere le caselle e un modulo newsletter interno per gli utenti registrati. I confini con Corsivo Newsletter sono descritti più sotto.

Come funziona

Moduli

• includes/settings/ — account SMTP/IMAP, opzioni, cifratura (crypto.php), import/export, pagina admin
• includes/smtp/ — configurazione PHPMailer per-account
• includes/queue/ — schema e verifica dello storage, coda, worker, endpoint cron, journal
• includes/storage/ — schema del log
• includes/template/ — CPT dei template, compilazione Gutenberg email-safe, merge tag, hook su wp_mail
• includes/automation/ — CPT automazioni, audience, invii manuali/bulk/programmati, eventi, email core
• includes/newsletter/ — modulo consensi interno: preferenza utente, unsubscribe, gruppi, blocco
• includes/imap/ — client TLS, sync, inbox e webmail admin
• includes/integrations/ — Corsivo Theme, Layouts, WPML, WooCommerce
• includes/api.php, includes/functions.php — API pubbliche per gli altri plugin

Entità dati

Tre tabelle InnoDB, tutte nel namespace {prefix}corsivo_mail_:

• corsivo_mail_queue — la coda. Colonne chiave: status (ciclo di vita pending, sending, transmitting, sent, failed, cancelled, delivery_unknown), locked_at/lock_token (lease), attempts/max_attempts, scheduled_at, idempotency_key (UNIQUE, hashata) con idempotency_fingerprint, source_type/source_id, source_guard_required, retain_until, message_type (transactional/marketing), payload leggibili (body come testo; headers, attachments, embeds come JSON), transport_started_at, error_code.
• corsivo_mail_log — journal append-only: event, queue_id, attempt, sorgente, account_id, actor_user_id, recipient più recipient_hash, subject, status, errore redatto, metadata filtrata su chiavi ammesse.
• corsivo_mail_messages — indice dei metadati IMAP (mittente, oggetto, data, uid, seen); i corpi non vengono persistiti. Installata solo con il modulo IMAP attivo.

Account SMTP/IMAP in un'option dedicata con password cifrate; impostazioni in corsivo_mail_settings.

Ciclo di vita di un invio

1. Accodamento. wp_mail viene intercettato su pre_wp_mail: se la coda è attiva il messaggio diventa una riga pending con payload plain leggibili e la chiamata ritorna true; short-circuit già impostati da altri plugin vengono rispettati. Messaggi con allegati o embed passano sincroni. Il filtro wp_mail applica il wrapping nel layout HTML (disattivabile). I plugin della suite accodano invece via API con chiave idempotente.
2. Claim. Il worker (cron ogni minuto) reclama le righe scadenzate con un singolo UPDATE atomico: pending diventa sending, lock_token UUID, attempts incrementato. Nessun'altra istanza può prendere la stessa riga.
3. Guardie. Prima del trasporto: fence della sorgente (corsivo_mail_queue_source_guard_{source_type} deve autorizzare le righe con guard obbligatoria), consenso marketing rivalutato al momento dell'invio per message_type = marketing (un solo destinatario, altrimenti soppressione).
4. Trasporto. La riga passa a transmitting (transport_started_at valorizzato, fence su cancel_requested), poi wp_mail parte con l'account SMTP della riga via PHPMailer.
5. Esito. Solo un esito confermato dal trasporto chiude la riga come sent (payload azzerati). Un fallimento segnalato viene ritentato con backoff esponenziale e jitter fino a max_attempts, poi failed. Un esito non verificabile dopo l'avvio del trasporto — eccezione, worker morto a metà — termina come delivery_unknown: mai retry cieco di un invio che potrebbe essere partito. sent significa "il trasporto ha accettato", non "la casella ha consegnato".
6. Terminale. Ogni chiusura (sent, failed, cancelled, delivery_unknown) emette corsivo_mail_queue_terminal con l'identità della sorgente, così Bookings e Members riconciliano il proprio stato.

Il recupero delle righe stantie gira a ogni ciclo: sending scadute tornano pending (o failed con worker_died a tentativi esauriti), transmitting scadute diventano delivery_unknown, le richieste di cancellazione della sorgente vengono onorate.

Storage e installazione

Lo schema è verificato fisicamente: engine InnoDB, colonne, indici e inventario del namespace devono corrispondere esattamente al codice corrente. L'installazione è fresh-only a due fasi (intent, creazione verificata, marker plain finale) sotto lock di database e accetta soltanto il formato corrente. Uno schema completo e fisicamente esatto viene riattestato anche se già popolato; uno schema incoerente o dati inattesi bloccano il runtime fail-closed con errore persistito e notice admin, senza toccare i dati esistenti.

La coda ha anche verifiche di integrità di dominio: payload attivi leggibili e strutturalmente validi, ciclo di vita coerente, policy delle sorgenti garantite rispettata.

Cron

• corsivo_mail_process_queue — ogni minuto: automazioni programmate (priorità 5) e poi la coda.
• corsivo_mail_cleanup_queue — giornaliero: retention di coda e log; le sorgenti possono alzare la propria via corsivo_mail_queue_source_retention_days, retain_until è sempre rispettato.
• Endpoint esterno /?corsivo_mail_cron={chiave} (o header X-Corsivo-Mail-Key, o Authorization: Bearer): esegue schedule e coda, risponde 503 a storage non disponibile. Chiave rigenerabile dalle impostazioni.

Punti rilevanti

• Coda durevole con lease. Claim atomico, lock token per ogni transizione, requeue delle righe abbandonate, backoff esponenziale con jitter. Nessuna email viene processata da due worker contemporaneamente, nessuna resta bloccata per sempre.
• Idempotenza. La chiave idempotente (hashata, UNIQUE) è accompagnata da una fingerprint canonica del payload: il replay della stessa richiesta restituisce la riga esistente, una chiave riusata con payload diverso è un errore esplicito. Il vincolo è del database, non del codice chiamante.
• Stati onesti. delivery_unknown esiste perché "non so se è partita" è diverso sia da sent sia da failed: dopo l'avvio del trasporto un esito non confermato non viene mai ritentato alla cieca né spacciato per consegnato.
• Cifratura con chiave propria. AES-256-GCM in envelope cmenc:v3 (versione, algoritmo, key_id, nonce, tag, ciphertext). La master key è letta da CORSIVO_MAIL_ENCRYPTION_KEY oppure generata una sola volta e persistita in corsivo_mail_encryption_master_key (non autoload, INSERT IGNORE per essere atomica tra worker concorrenti); da lì hash_hkdf deriva la chiave di payload. Non dipende dai salt WordPress: ruotarli non rende illeggibile nulla. L'AAD lega plugin, blog, versione, key_id e tipo di credenziale, quindi una password SMTP non può essere spostata nel campo IMAP. Cifra esclusivamente le credenziali SMTP/IMAP; i payload della coda restano testo e JSON leggibili. I payload vengono azzerati alla chiusura della riga (sent, cancelled, delivery_unknown); restano leggibili sulle righe failed per permettere il retry manuale, fino alla retention.
• Log senza segreti. Il log conserva destinatario e oggetto ma mai body, header, allegati o credenziali; gli errori sono redatti (password/token e query string rimossi dalle URL). Accanto al destinatario c'è recipient_hash, SHA-256 stabile dell'indirizzo normalizzato: non dipende da HMAC o salt WordPress e serve per correlare le righe e per gli strumenti privacy di WordPress (exporter ed eraser coprono log e coda).
• Fail-closed. Senza storage verificabile il runtime non si carica: quando Corsivo Mail governa il trasporto, gli invii vengono bloccati invece di uscire non tracciati; worker ed endpoint cron rispondono unavailable. Il kill switch disable_sending sopprime ogni invio con traccia a log.
• Sorgenti garantite. Le email di Bookings e Members (corsivo-bookings-payment-request, corsivo-bookings-stay-reminder, corsivo-members-expiry, corsivo-members-renewal) esigono guard attiva e retain_until di almeno 8 giorni; l'accodamento senza policy corretta viene rifiutato. Le sorgenti dispongono di fence durevole (cancel_requested) e cancellazione verificata.
• Confini con Corsivo Newsletter. Sovrapposizione dichiarata: Mail include un modulo newsletter interno (consenso in user_meta per utenti registrati, blocco iscrizione, unsubscribe HMAC con one-click) che copre solo il caso "utenti del sito". Corsivo Newsletter possiede l'audience esterna con double opt-in, i provider e le campagne. Quando Newsletter è attivo il modulo interno parte disabilitato per mantenere una sola fonte di verità e il consenso marketing viene delegato allo stato confirmed dell'iscritto esterno, riverificato dal worker prima di ogni trasporto.
• IMAP difensivo. TLS con verifica del peer, limite sulla dimensione delle risposte, HTML remoto sanitizzato e servito con CSP sandbox in documenti isolati. La webmail è solo per amministratori.
• Superficie amministrativa chiusa. CPT di template e automazioni con capability manage_options, route REST amministrative autenticate.

Integrazioni con la suite

API per le sorgenti (Bookings, Members, chiunque registri email):

corsivo_mail_enqueue_registered($provider_id, $to, $context, $idempotency_key, $source);
corsivo_mail_fence_queued($queue_id, $source_type, $source_id);
corsivo_mail_cancel_queued($queue_id, $source_type, $source_id, $error_code);
corsivo_mail_queue_status($queue_id, $source_type, $source_id);

corsivo_mail_deliver($core_email_id, $to, $context, $headers);
corsivo_mail_core_email_status($core_email_id);
corsivo_mail_send($post_id, $to, $context);

• Bookings / Members → coda. Accodano email registrate con idempotenza e policy di retention; l'action corsivo_mail_queue_terminal notifica l'esito, il filtro corsivo_mail_queue_source_guard_{source_type} è il veto della sorgente al momento dell'invio.
• Email core registrabili. Il filtro corsivo_mail_core_emails registra email con template a blocchi editabile: il core WordPress (reset password, nuovo utente) è già coperto; Corsivo Newsletter vi registra corsivo_newsletter_confirm e la consegna con corsivo_mail_deliver.
• Newsletter → audience. Corsivo Newsletter pubblica gli iscritti confermati come audience delle automazioni via corsivo_mail_audiences, corsivo_mail_resolve_recipients, corsivo_mail_recipient_count, con merge tag unsubscribe_url.
• Estensione. Eventi (corsivo_mail_events), merge tag (corsivo_mail_merge_tags; {{meta:chiave}} solo per chiavi ammesse via corsivo_mail_user_meta_keys), rendering (corsivo_mail_base_styles, corsivo_mail_color_palette, corsivo_mail_font_sizes, corsivo_mail_spacing_scale, corsivo_mail_document_head, corsivo_mail_starter_templates), trasporto (corsivo_mail_smtp_presets, corsivo_mail_smtp_timeout, corsivo_mail_imap_max_response_bytes, corsivo_mail_editor_recipient_limit).
• Integrazioni opzionali. WooCommerce (le email native restano a WooCommerce: né wrapping né coda), WPML (risoluzione di automazioni e layout nella lingua del destinatario), Corsivo Theme (palette e font ereditati quando abilitato e rilevato), Corsivo Layouts (starter template via filtro).

Test

Con WordPress caricato (WP-CLI):

wp eval-file wp-content/plugins/corsivo-mail/tests/database-integrity.php
wp eval-file wp-content/plugins/corsivo-mail/tests/queue-storage.php
wp eval-file wp-content/plugins/corsivo-mail/tests/security-queue.php
wp eval-file wp-content/plugins/corsivo-mail/tests/transport-contract.php
wp eval-file wp-content/plugins/corsivo-mail/tests/footer-layout.php
wp eval-file wp-content/plugins/corsivo-mail/tests/queue-lifecycle-integrity.php

• database-integrity — engine InnoDB e colonne reali delle tre tabelle.
• queue-storage — macchina a stati dello storage: installazione, recovery, condizioni di blocco.
• security-queue — autorizzazioni REST e CPT, payload coda plain, roundtrip e tamper delle credenziali cifrate, sanitizzazione HTML IMAP, soppressione marketing multi-destinatario e consenso esterno.

Esistono anche admin-render.php (rendering di tutti i tab admin) e transfer-roundtrip.php (import/export), sempre via wp eval-file.

Eseguire le suite database su un'installazione di test isolata: creano fixture, alterano temporaneamente opzioni e schemi e verificano anche la pulizia della coda. queue-lifecycle-integrity verifica completamenti tardivi, fence pendenti e retention minima delle sorgenti protette.

Standalone, senza WordPress:

php wp-content/plugins/corsivo-mail/tests/crypto-early-boot.php
php wp-content/plugins/corsivo-mail/tests/storage-plain-early-boot.php
php wp-content/plugins/corsivo-mail/tests/schema-current-static.php
php wp-content/plugins/corsivo-mail/tests/admin-navigation.php
php wp-content/plugins/corsivo-mail/tests/storage-defaults.php
php wp-content/plugins/corsivo-mail/tests/queue-input-contract.php
php wp-content/plugins/corsivo-mail/tests/smtp-account-isolation.php
php wp-content/plugins/corsivo-mail/tests/marketing-recipient-contract.php
php wp-content/plugins/corsivo-mail/tests/imap-protocol.php
php wp-content/plugins/corsivo-mail/tests/template-content-contract.php

I primi due dimostrano che cifratura delle credenziali e verifica dello stato storage funzionano early-boot (fail-closed quando non c'è né costante né database, nessun caricamento di pluggable.php); schema-current-static.php impedisce la reintroduzione di installer lazy, del versioning di schema e di qualunque ritorno dei salt WordPress dentro crypto.php; admin-navigation.php verifica il gate developer della sola voce Impostazioni e la landing operativa su Email.

Le altre regressioni coprono i default MySQL/MariaDB, il roundtrip dei payload wp_mail, l'isolamento degli account SMTP, il consenso marketing senza copie, i protocolli IMAP/MIME e il rendering di oggetti e liste. Usano fixture locali senza connessioni a server di posta.

Configurazione

• Navigazione amministrativa. Il menu principale Email (posizione 31) apre Messaggi, per gli invii manuali e automatici; seguono Posta in arrivo (modulo opzionale), Modelli, Footer e Impostazioni. Il menu Impostazioni rimane visibile solo agli utenti con manage_corsivo_developer_tools; la pagina diretta continua a richiedere manage_options. Tutte le voci appartengono a Mail e funzionano senza altri plugin Corsivo.
• Account. SMTP multipli con preset (Gmail, Aruba, OVH, Microsoft 365, Brevo, SendGrid, ecc.), mittente e account predefinito; credenziali cifrate al salvataggio, mai riproposte in chiaro. IMAP opzionale per account.
• Coda. use_queue, batch size (default 20), retry massimi (3), pausa tra invii, minuti di lock (10), retention coda (30 giorni) e log (90).
• Trasporto. wrap_wp_mail per il wrapping del layout, disable_sending come kill switch globale.
• Moduli. IMAP e preferenze newsletter interne attivabili dal tab Moduli, insieme alle integrazioni Corsivo Theme, WPML e WooCommerce; chiavi meta utente ammesse come merge tag.
• Cron esterno. URL con chiave dedicata, rigenerabile dalle impostazioni, per siti senza traffico regolare.
• Chiave di cifratura. Facoltativa: senza di essa la master key viene generata al primo uso e salvata a database.

define('CORSIVO_MAIL_ENCRYPTION_KEY', 'inserisci-almeno-32-byte-casuali');

Definirla tiene la chiave fuori dal database, così un dump non basta a leggere le credenziali. Una volta scelta va mantenuta stabile e inclusa nei backup: cambiarla o rimuoverla rende illeggibili le credenziali salvate, che vanno reinserite. Ruotare i salt WordPress invece non ha alcun effetto.

• Requisiti. WordPress 6.6+, PHP 8.1+, OpenSSL con AES-256-GCM.

L'editor Gutenberg, la Posta in arrivo e i tab React Account/Gruppi vengono compilati rispettivamente da admin-editor, inbox-app e settings-app, incorporando il package privato @corsivo-suite/wp-admin-ui. In ciascuna directory npm install seguito da npm run check rigenera gli asset, verifica i controlli e valida il wiring PHP. Se una build è incompleta, WordPress carica lo script classico e il relativo CSS in assets senza interrompere l'interfaccia.

Bootstrap, entry point e lifecycle

corsivo-mail.php carica per primi soltanto i componenti necessari a leggere configurazione e stato dello storage: cifratura/account/opzioni, schema della coda e del log/IMAP, primitive della coda, worker ed endpoint cron. Questa parte early-boot può quindi verificare lo storage e, se Corsivo Mail governa il trasporto globale, bloccare wp_mail senza dipendere dal runtime applicativo. Il filtro conserva qualunque short-circuit già deciso da un componente precedente.

load_runtime() include il resto soltanto dopo required_storage_ready(): sicurezza e admin, SMTP e journal, template e blocchi, automazioni, newsletter interna, IMAP, integrazioni e API pubblica. L'ordine evita che CPT, route o worker diventino parzialmente disponibili quando le tabelle richieste non sono verificabili.

L'attivazione installa lo storage fresh-only, registra CPT e cron e verifica subito il risultato; la disattivazione elimina le pianificazioni e i flag di verifica, senza cancellare coda, log, template o account. uninstall.php è il solo percorso che elimina tabelle, opzioni, meta, cron e contenuti di servizio del plugin. Non esiste un installer lazy nel traffico ordinario.

Gli entry point sono: intercettazione pre_wp_mail; funzioni PHP pubbliche in includes/api.php; route REST amministrative per configurazione, template, automazioni e inbox; hook cron interno ed endpoint cron autenticato; schermate WordPress; blocco newsletter e componenti dell'editor; integrazione PHPMailer e, quando abilitato, sincronizzazione IMAP.

Mappa completa dei file

Contratti di rendering e consegna

I merge tag vengono espansi una sola volta nel template. Il corpo ricevuto da wp_mail resta contenuto e non viene interpretato come template. Gli oggetti email usano sostituzioni testuali; i valori HTML ordinari rimangono escaped. Un'integrazione può indicare esplicitamente campi HTML nel contesto con _html_keys, per esempio ['fields_html']: questi valori passano attraverso wp_kses_post prima dell'inserimento.

Se PHPMailer conferma la consegna ad almeno un destinatario e restituisce un errore per gli altri, la coda passa a delivery_unknown senza reinvio automatico. Il dettaglio segnala la consegna parziale. Quando tutti i destinatari sono rifiutati rimane disponibile il normale retry.

Una ricorrenza mensile impostata al 29, 30 o 31 viene eseguita l'ultimo giorno disponibile nei mesi più corti. I worker HTTP firmati partono su wp_loaded, dopo la registrazione di blocchi, post type e integrazioni. tests/audit-regressions.php verifica questi contratti senza WordPress avviato, database o rete.

La sincronizzazione IMAP incrementale importa i nuovi UID in ordine, senza saltare i messaggi che superano il batch. Lettura, allegati e cancellazione richiedono la stessa UIDVALIDITY nella lista del browser, nella cache e sul server; una casella ricreata richiede una nuova sincronizzazione prima di operare sui messaggi. php tests/imap-identity.php verifica backlog e identità dei messaggi senza connessioni esterne.

Il parser IMAP legge UID, flag e data esclusivamente dai metadati FETCH esterni al contenuto ricevuto. php tests/imap-fetch-parser.php verifica risposte con metadati prima o dopo il literal, notifiche intermedie e header contenenti falsi metadati.