Come spedire via Simply SMTP con autenticazione OAuth 2.0

Configura l’applicazione Simply SMTP con autenticazione OAuth 2.0 e utilizza magnews come server di posta in uscita per l'invio di messaggi email transazionali.

Autenticazione con OAuth 2.0

Premessa: i parametri e le configurazioni suggerite in questa pagina potrebbero non essere adatti per situazioni particolari o installazioni magnews On premise. Prima di procedere, ti consigliamo di verificare con il nostro Help Desk che le indicazioni fornite siano appropriate per la tua infrastruttura.

Per motivi di sicurezza, utilizziamo un servizio di monitoraggio per la scadenza delle password degli utenti di piattaforma.

Se la password dell'utente che hai creato per gestire i servizi di Simple Mail Transfer Protocol (SMTP) dovesse scadere, il servizio smetterà di funzionare.

Per riattivare il servizio, dovrai creare una nuova password e aggiornarla nelle applicazioni che usano quel servizio.

Pertanto, ti suggeriamo di usare una soluzione che eviti di dover aggiornare la password, implementando il protocollo OAuth 2.0 (https://oauth.net/2/).

Questa soluzione garantisce - assieme all'uso di token generati da magnews - un sistema di autenticazione più sicuro, con l'ulteriore beneficio di garantire privilegi di accesso individuali e di revocarli senza inibire l'accesso ai servizi da parte di un utente.

Il primo passo per implementare questa procedura è di creare un certificato digitale per la tua applicazione.
Il certificato è indispensabile per richiedere un access token ed un refresh token, mediante i quali la tua applicazione possa rinnovare automaticamente i token in scadenza.

Crea un certificato digitale

Accedi al menu Impostazioni e poi alla sezione Web service > Certificati digitali

Crea un nuovo certificato e, per il campo Tipo di certificato, scegli l'opzione Applicazione Client (OAuth 2.0)

Nel campo Nome inserisci l'etichetta del certificato (serve solo per identificarlo su magnews).

Inserisci i dati riferiti a:

• ID applicazione: necessario per il parametro client_id
• Display Name: mostrato all’utente nel form di richiesta autorizzazione
• App Secret: obbligatorio solo in alcuni casi (es. per i client solo js); è possibile modificarlo e non è mostrato per ragioni di sicurezza
• OAuth redirect URI: obbligatorio solo se il certificato è utilizzato da un'applicazione web

Funzioni di utilità

Dopo aver creato il certificato, nella stessa pagina appare la sezione Funzioni di utilità con informazioni su:

• Token location URL: indirizzo per trasformare i parametri forniti in un access token o per usare un refresh token
• Informazioni sul token: link descrittivo sul token
• Ricevi token di accesso: pulsante che permette di ottenere subito un access token OAuth 2.0
• REST API Explorer: per eseguire test di API REST su magnews

Ottieni un Accesso token

Una volta creato il certificato digitale, puoi ottenere un access token immediato.

Clicca su Ricevi token d'accesso, per visualizzare tutte le informazioni sul token.

Puoi modificare la durata del token (di default impostata a quattro ore) o annullarne la validità immediatamente (pulsante Revoca accesso).

Client e lunghezza dei token

Alcuni client hanno il campo lunghezza password più corto rispetto al numero di caratteri che compongono i token.

In questo caso, si corre il rischio che il client risponda che le credenziali di accesso sono errate. Se riscontri questa criticità, contatta il nostro Help Desk, che ti aiuterà a risolverla.

Importante: il client SMTP che utilizzi deve essere configurato per l'uso di connessioni attraverso il canale sicuro STARTTLS. Qualora non fosse adottata questa metodologia di connessione, falliranno i tentativi di autenticazione e l'integrazione con la soluzione Simply SMTP non funzionerà.

Configurazione ed utilizzo Simply SMTP

Creazione di un utente dedicato

Il primo passo per la configurazione del Simply SMTP è la creazione di un utente dedicato a questo servizio.

Per creare l’utente, accedi al menu Impostazioni e poi alla sezione Utenti e sicurezza > Utenti. Clicca su Nuovo utente e procedi alla sua configurazione.

Copia e tieni al sicuro il nome utente (anche chiamato username) e la password dell'utente creato, ti serviranno in seguito per la configurazione del Simply SMTP.

Importante: dopo aver creato l’utente, contatta il nostro Help Desk per attivare il permesso di spedizione, necessario all'invio di messaggi con il Simply SMTP.

Creazione di una categoria transazionale

Il secondo passo è quello della creazione di una categoria transazionale, all'interno della quale sarà creato il tipo di messaggio dedicato all'invio da Simply SMTP.

Il tipo di messaggio è utile per identificare, nella sezione Insight, i report dedicati alle email transazionali spedite con il Simply SMTP.

Per accedere alla pagina di gestione delle categorie segui il menu Journey Lab > Impostazioni > Categorie transazionali.

Clicca su Nuova categoria, assegnale un Nome e clicca su Crea categoria

Creazione di un tipo di messaggio

Adesso definisci il Tipo di messaggio.

Segui il menu Journey Lab > Impostazioni > Tipi di transazionali e clicca su Nuovo tipo di messaggio

Seleziona la categoria di appartenenza, definisci il Nome del tipo di messaggio e decidi se i messaggi di questo tipo devono essere inviati anche ai contatti disiscritti su magnews.

Clicca su Crea tipo.

Configurazione del Simply SMTP

Per utilizzare il Simply SMTP segui il percorso Impostazioni > Sviluppatore > Simply SMTP

e configura le opzioni necessarie nella sezione Generale:

• Attiva Simply SMTP: attiva o disattiva il funzionamento del modulo
• Traccia le aperture e i click: attiva o disattiva il tracciamento degli eventi di apertura e click per i messaggi inviati
• Riconosci i contatti e aggiorna le loro statistiche: verifica se il destinatario del messaggio corrisponde ad un contatto presente nel database specificato; il messaggio viene associato al contatto riconosciuto e i suoi dati statistici sono aggiornati
• Database: seleziona il database di magnews in cui cercare i contatti; se la chiave del database non è l'email, il contatto è associato solo se l'email è univoca
• Iscrivi i nuovi contatti: i destinatari dei messaggi sono aggiunti come nuovi contatti, con associato lo stato iscritto; attenzione: sono gestiti dati personali e di profilazione dei contatti
• Provenienza: associa l'origine per ogni nuovo contatto inserito, così da filtrare i contatti e/o definire specifiche audience dinamiche
• Considera la Blacklist per i messaggi gestiti da Simply SMTP: per i recapiti in blacklist, il messaggio non sarà spedito e sarà generato un bounce in automatico
• Tipo di messaggio transazionale: indica il tipo di messaggio (vedi paragrafo “Creazione di un tipo di messaggio“) per registrare e visualizzare i dati statistici
• Journey per i link tracciati: se non è indicato un dominio web (campo sottostante), per i link dei messaggi inviati da Simply SMTP è utilizzato il dominio del journey selezionato
• Dominio web: dominio web associato ai link dei messaggi inviati da Simply SMTP
• Includi stili CSS inline nelle email HTML: puoi includere CSS inline nei tuoi messaggi, ma attenzione: potresti riscontrare un rallentamento nelle performance di invio

Può sorgere l'esigenza di spedire tipi diversi di messaggi e di volerli contrassegnare per organizzarli meglio e riconoscerli nelle statistiche.
A tal fine, come descritto nel paragrafo Creazione di un tipo di messaggio:

• Accedi alla pagina dei Tipi di messaggio
• Crea i tipi di messaggio di cui hai bisogno

• A fianco di ciascun tipo di messaggio noterai un numero; si tratta dell'ID del tipo di messaggio (idtype)

• Assegna a ciascun messaggio il proprio idtype

  Inserisci la seguente stringa nell'header di ciascuno messaggio transazionale: x-mn-idtype: {mio_id} dove {mio_id} è l'idtype mostrato nella lista dei tipi di transazionali
  Il risultato ottenuto sarà, ad esempio, il seguente:

Nella sezione Credenziali, invece, trovi tutti i parametri necessari a configurare il tuo servizio esterno per interfacciarsi con il Simply SMTP di magnews:

Lo Username mostrato è quello dell'utente con il quale si sta configurando il Simply SMTP.
Quando configuri il servizio esterno che utilizza il servizio Simply SMTP, inserisci come Username quello che hai creato seguendo le istruzioni del paragrafo “Creazione di un utente dedicato“, seguito dal simbolo @ e dal codice cliente del tuo account magnews, ad esempio: helpdesk@magnewsdoc.

Nel campo Password inserisci il token di accesso (vedi paragrafo “Ottieni un Accesso token“) o la password associata all'utente.

Header dei messaggi

Per i messaggi transazionali è possibile aggiungere alcuni dei seguenti header:

• x-mn-idtype: specifica il tipo di transazionale, indicando l'ID; es. x-mn-idtype: {mio_id_tipo}
• x-mn-cssinline: se attivi l’opzione Includi stili CSS inline nelle email HTML, include gli stili CSS inline, es. x-mn-cssinline: true
• x-mn-iddb: se attivi l'opzione Iscrivi i nuovi contatti, puoi indicare l'ID del database in cui aggiungere i contatti; es. x-mn-iddb: 1
• x-mn-webdomain: specifica un dominio web per i link tracciati del messaggio; es. x-mn-webdomain: {Nome_dominio_web}
• x-mn-externalid: assegna al messaggio un id esterno (stringa), utilizzato per identificare il messaggio da app o in altre operazioni; es. x-mn-externalid: {id esterno}
• x-mn-idpolicy: specifica l'ID di una delivery policy da utilizzare per l'invio del messaggio; es. x-mn-idpolicy: 4
• x-mn-donotcreatesimplemessage: se indichi true il messaggio è creato e sono eseguite le verifiche pre-invio, ma il messaggio non viene effettivamente spedito; es. x-mn-donotcreatesimplemessage: true