mailinapp
Documentation menu

Salesforce

MailInApp n'a pas d'application Salesforce à installer — vous n'en avez pas besoin. L'API REST propre de Salesforce répond en JSON brut via HTTPS, et la source de données API de MailInApp avec l'authentification OAuth2 JWT Bearer est conçue pour parler directement le flux de connexion serveur à serveur de Salesforce : pas d'écran de consentement interactif, pas de jeton de rafraîchissement à surveiller, et votre mot de passe Salesforce ne touche jamais MailInApp.

Ce guide met en place une connexion en lecture seule — en récupérant des lignes Opportunity, Account ou Contact dans des balises de fusion, des blocs de répétition et des blocs graphiques liés en direct. Il n'écrit rien dans Salesforce.

Comment fonctionne la connexion

  1. MailInApp signe une assertion JWT de courte durée avec la clé privée de votre Connected App Salesforce.
  2. Il envoie cette assertion en POST à l'endpoint de jeton de Salesforce, qui vérifie la signature par rapport au certificat que vous avez téléversé et renvoie un jeton d'accès — aucun nom d'utilisateur ni mot de passe n'est jamais envoyé.
  3. MailInApp met en cache le jeton d'accès et appelle l'API REST de Salesforce (une requête SOQL) avec celui-ci comme jeton Bearer, en le rafraîchissant automatiquement avant son expiration ou si un appel revient non autorisé.

Chaque étape se déroule côté serveur, à chaque récupération — il n'y a rien à maintenir actif ni à réautoriser manuellement une fois la configuration effectuée.

Configurer le côté Salesforce

  1. Dans Salesforce Setup, allez dans App Manager → New Connected App (ou New Connected App (Lightning)).
  2. Remplissez les champs de base nom/email, puis cochez Enable OAuth Settings.
  3. Sous Use digital signatures, téléversez un certificat. Si vous n'en avez pas déjà un, générez un certificat auto-signé et sa clé privée RSA correspondante — le certificat va à Salesforce, la clé privée va à MailInApp. Conservez la clé privée en lieu sûr ; vous la collerez une fois dans MailInApp, après quoi elle sera masquée.
  4. Ajoutez le scope OAuth dont votre intégration a besoin — api (Manage user data via APIs) suffit pour lire des enregistrements.
  5. Enregistrez, puis modifiez les politiques du Connected App : réglez Permitted Users sur Admin approved users are pre-authorized. C'est ce qui rend le flux non interactif — sans cela, Salesforce s'attend à ce qu'un humain clique sur un écran de consentement, ce qu'un échange JWT serveur à serveur ne peut pas faire.
  6. Affectez l'utilisateur d'intégration (un véritable utilisateur Salesforce avec l'accès API activé sur son profil, ou un utilisateur dédié uniquement à l'intégration) au Connected App via un permission set.
  7. Notez le Consumer Key du Connected App — c'est l'issuer dont MailInApp a besoin — ainsi que l'URL My Domain de votre org (Setup → My Domain), par ex. https://yourorg.my.salesforce.com.

Connectez-le dans MailInApp

Depuis Data Sources → + API connection, définissez :

  • Endpoint — l'URL de requête REST de votre org, par ex. https://yourorg.my.salesforce.com/services/data/v61.0/query?q=SELECT+Name,Amount,StageName,CloseDate+FROM+Opportunity+WHERE+IsClosed+=+false (une requête SOQL encodée en URL — voir Interroger avec SOQL ci-dessous).
  • Data path — records. La réponse de requête de Salesforce enveloppe les lignes réelles dans un tableau records, accompagné des champs totalSize/done.
  • Authentication — OAuth2 JWT Bearer :
    • Token URL — https://login.salesforce.com/services/oauth2/token pour les orgs de production et Developer Edition, https://test.salesforce.com/services/oauth2/token pour un sandbox.
    • Issuer — le Consumer Key du Connected App.
    • Subject — le nom d'utilisateur Salesforce de l'utilisateur d'intégration (l'identité affirmée par le JWT).
    • Audience — le même hôte que l'URL du jeton : https://login.salesforce.com (ou https://test.salesforce.com pour un sandbox).
    • Private key — la clé privée RSA associée au certificat que vous avez téléversé sur le Connected App.

Cliquez sur Test these settings pour confirmer la connexion avant d'enregistrer — cela génère un vrai jeton et affiche un aperçu des premières lignes. Une fois enregistrée, utilisez Test saved connection à tout moment par la suite pour la revérifier sans avoir à recoller la clé privée.

Interroger avec SOQL

La chaîne de requête de l'endpoint est la donnée que vous récupérez — il n'y a pas d'interface distincte pour « choisir vos champs », donc façonnez la requête SOQL pour renvoyer exactement les colonnes dont votre email a besoin :

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

Quelques points à connaître sur la forme de ce qui revient :

  • Champs plats uniquement. Un champ de relation comme Owner.Email ou Account.Name revient sous forme d'objet JSON imbriqué ({"Owner": {"Email": "..."}}), et l'analyseur de lignes de MailInApp abandonne les valeurs imbriquées plutôt que de deviner comment les aplatir. Si vous avez besoin d'un identifiant de propriétaire ou de compte comme balise de fusion utilisable, sélectionnez plutôt un champ plat — OwnerId, par exemple — au lieu d'un chemin de relation en pointillé.
  • Jusqu'à 1 000 lignes par récupération. Largement suffisant pour un email de synthèse ou de tableau de bord ; affinez davantage avec WHERE/ORDER BY/LIMIT directement dans la requête si vous ne voulez qu'une tranche spécifique.
  • Récupéré à nouveau à chaque rendu. Un envoi récurrent réexécute la requête et rend à nouveau les blocs liés avec les lignes actuelles de Salesforce à chaque envoi — il n'y a pas de mise en cache au-delà du jeton OAuth lui-même.

Utiliser les données

Une fois connectée, ajoutez-la à un projet depuis le panneau Données du studio avec un alias (par ex. pipeline) et un rôle :

  • Champs de fusion résolvent {{pipeline.field}} à partir de la première ligne renvoyée — utile pour un chiffre clé unique.
  • Lignes répétées alimentent un bloc de répétition — une ligne par Opportunity, rendue sous forme de liste ou de tableau.
  • Les liaisons Collection sont ce à quoi se lient directement les blocs de tableau de bord KPI, barres, lignes et camembert — le champ Value d'un tableau de bord KPI réglé sur Amount avec un agrégat Sum vous donne un chiffre « pipeline ouvert total » en direct sans aucune plomberie de balise de fusion, et un graphique à barres groupé par StageName transforme la même requête en une répartition du pipeline par étape.

Voir Email interactif alimenté par des données Salesforce en direct pour un exemple complet — une synthèse hebdomadaire du pipeline entièrement construite à partir de cette connexion.