mailinapp
Documentation menu

Salesforce

MailInApp non ha un'app Salesforce da installare — non te ne serve una. La REST API nativa di Salesforce risponde con JSON semplice via HTTPS, e la fonte dati API di MailInApp con autenticazione OAuth2 JWT Bearer è costruita per parlare direttamente il flusso di login server-to-server di Salesforce: nessuna schermata di consenso interattiva, nessun refresh token da tenere sotto controllo, e la tua password Salesforce non tocca mai MailInApp.

Questa guida configura una connessione in sola lettura — che porta righe di Opportunity, Account o Contact in tag di personalizzazione, blocchi di ripetizione e blocchi grafico legati ai dati live. Non scrive mai verso Salesforce.

Come funziona la connessione

  1. MailInApp firma un'asserzione JWT di breve durata con la chiave privata della tua Connected App Salesforce.
  2. La invia via POST all'endpoint token di Salesforce, che verifica la firma rispetto al certificato che hai caricato e restituisce un token di accesso — senza inviare mai nome utente o password.
  3. MailInApp memorizza nella cache il token di accesso e chiama la REST API di Salesforce (una query SOQL) usandolo come token Bearer, aggiornandolo automaticamente prima che scada o se una chiamata torna mai non autorizzata.

Ogni passaggio avviene lato server, a ogni recupero — non c'è nulla da tenere attivo o da riautorizzare a mano una volta configurato.

Configura il lato Salesforce

  1. In Salesforce Setup, vai su App Manager → New Connected App (oppure New Connected App (Lightning)).
  2. Compila i campi base di nome/email, poi seleziona Enable OAuth Settings.
  3. Sotto Use digital signatures, carica un certificato. Se non ne hai già uno, genera un certificato autofirmato e la sua chiave privata RSA corrispondente — il certificato va a Salesforce, la chiave privata va a MailInApp. Conserva la chiave privata in un posto sicuro; la incollerai in MailInApp una volta sola e da quel momento sarà mascherata.
  4. Aggiungi l'ambito OAuth di cui ha bisogno la tua integrazione — api (Manage user data via APIs) è sufficiente per leggere i record.
  5. Salva, poi modifica i criteri della Connected App: imposta Permitted Users su Admin approved users are pre-authorized. Questo è ciò che rende il flusso non interattivo — senza di esso, Salesforce si aspetta che una persona clicchi su una schermata di consenso, cosa che uno scambio JWT server-to-server non può fare.
  6. Assegna l'utente di integrazione (un vero utente Salesforce con accesso API abilitato sul proprio profilo, oppure un utente dedicato solo all'integrazione) alla Connected App tramite un permission set.
  7. Prendi nota della Consumer Key della Connected App — è l'issuer di cui ha bisogno MailInApp — e dell'URL My Domain della tua org (Setup → My Domain), ad es. https://yourorg.my.salesforce.com.

Collegala in MailInApp

Da Fonti dati → + Connessione API, imposta:

  • Endpoint — l'URL di query REST della tua org, ad es. https://yourorg.my.salesforce.com/services/data/v61.0/query?q=SELECT+Name,Amount,StageName,CloseDate+FROM+Opportunity+WHERE+IsClosed+=+false (una query SOQL con codifica URL — vedi Interrogare con SOQL più sotto).
  • Percorso dati — records. La risposta di query di Salesforce racchiude le righe effettive in un array records insieme ai campi totalSize/done.
  • Autenticazione — OAuth2 JWT Bearer:
    • URL del token — https://login.salesforce.com/services/oauth2/token per org di produzione e Developer Edition, https://test.salesforce.com/services/oauth2/token per un sandbox.
    • Issuer — la Consumer Key della Connected App.
    • Subject — il nome utente Salesforce dell'utente di integrazione (l'identità che il JWT asserisce).
    • Audience — lo stesso host dell'URL del token: https://login.salesforce.com (oppure https://test.salesforce.com per un sandbox).
    • Chiave privata — la chiave privata RSA abbinata al certificato che hai caricato sulla Connected App.

Clicca Testa queste impostazioni per confermare la connessione prima di salvare — genera un token reale e mostra un'anteprima delle prime righe. Una volta salvata, usa Testa connessione salvata in qualsiasi momento successivo per riverificarla senza reincollare la chiave privata.

Interrogare con SOQL

La stringa di query dell'endpoint è il dato che ottieni indietro — non esiste un'interfaccia separata per "scegli i tuoi campi", quindi modella la query SOQL per restituire esattamente le colonne di cui la tua email ha bisogno:

SELECT Name, Amount, StageName, CloseDate FROM Opportunity WHERE IsClosed = false

Alcune cose utili da sapere sulla forma di ciò che torna indietro:

  • Solo campi piatti. Un campo di relazione come Owner.Email o Account.Name torna indietro come oggetto JSON annidato ({"Owner": {"Email": "..."}}), e il parser di righe di MailInApp scarta i valori annidati invece di provare a indovinare come appiattirli. Se ti serve un identificatore di proprietario o account come tag di personalizzazione utilizzabile, seleziona invece un campo piatto — OwnerId, ad esempio — anziché un percorso di relazione con il punto.
  • Fino a 1.000 righe per recupero. Più che sufficiente per un digest o un'email dashboard; restringi ulteriormente con WHERE/ORDER BY/LIMIT direttamente nella query se ti serve solo una porzione specifica.
  • Recuperato fresco a ogni rendering. Un invio ricorrente riesegue la query e ri-renderizza i blocchi legati con le righe attuali di Salesforce a ogni invio — non c'è alcuna cache oltre al token OAuth stesso.

Usare i dati

Una volta collegata, aggiungila a un progetto dal pannello Dati dello studio con un alias (ad es. pipeline) e un ruolo:

  • I campi di personalizzazione risolvono {{pipeline.field}} dalla prima riga restituita — utile per una singola cifra in evidenza.
  • Le righe di ripetizione alimentano un blocco di ripetizione — una riga per Opportunity, renderizzata come elenco o tabella.
  • Le associazioni Collection sono ciò a cui si legano direttamente i blocchi scheda KPI, a barre, a linee e a torta — una scheda KPI con il campo Valore impostato su Amount e un aggregato Sum ti dà un numero live "pipeline aperta totale" senza alcuna configurazione di tag di personalizzazione, e un grafico a barre raggruppato per StageName trasforma la stessa query in una ripartizione della pipeline per fase.

Vedi Email interattiva alimentata da dati Salesforce live per un esempio completo dettagliato — un digest settimanale della pipeline costruito interamente a partire da questa connessione.