Salesforce
Für MailInApp gibt es keine Salesforce-App zu installieren, und Sie brauchen auch keine. Die REST-API von Salesforce antwortet mit einfachem JSON über HTTPS. Die API-Datenquelle von MailInApp spricht mit der Authentifizierung OAuth2 JWT Bearer direkt den Server-zu-Server-Anmeldefluss von Salesforce: kein Zustimmungsbildschirm, kein Refresh-Token zu pflegen, und Ihr Salesforce-Passwort erreicht MailInApp nie.
Diese Anleitung richtet eine schreibgeschützte Verbindung ein. Sie holt Opportunity-, Account-, Contact- oder Produktzeilen in Merge-Tags, Wiederholungsblöcke und verknüpfte Diagramme und kann Ihre Salesforce-Kontakte als Zielgruppe importieren. Sie schreibt nichts nach Salesforce zurück.
So funktioniert die Verbindung
- MailInApp signiert eine kurzlebige JWT-Assertion mit dem privaten Schlüssel Ihrer App.
- Es sendet diese Assertion an den Token-Endpunkt von Salesforce. Salesforce prüft die Signatur mit dem hochgeladenen Zertifikat und gibt ein Zugriffstoken zurück. Es werden weder Benutzername noch Passwort gesendet.
- MailInApp speichert das Token zwischen und ruft damit die REST-API von Salesforce auf (eine SOQL-Abfrage). Vor dem Ablauf, oder wenn ein Aufruf als nicht autorisiert zurückkommt, holt es ein neues.
Alles geschieht serverseitig, bei jedem Abruf. Einmal eingerichtet, müssen Sie nichts am Leben halten oder neu autorisieren.
Ein Schlüsselpaar erstellen
Der JWT-Fluss braucht ein RSA-Schlüsselpaar: Das Zertifikat geht an Salesforce, der private Schlüssel an MailInApp. Wenn Sie keines haben, erzeugen Sie mit OpenSSL ein selbstsigniertes Paar:
openssl req -x509 -newkey rsa:2048 -nodes -keyout mailinapp.key -out mailinapp.crt -days 730 -subj "/CN=MailInApp"
Bewahren Sie mailinapp.key sicher auf. Sie fügen ihn einmal in MailInApp ein, danach wird er maskiert.
Salesforce einrichten
Salesforce legt neue Integrationen inzwischen als External Client Apps an (neue Connected Apps sind in aktuellen Orgs standardmäßig deaktiviert).
- Öffnen Sie in Setup den External Client App Manager und klicken Sie auf New External Client App.
- Geben Sie den Namen (zum Beispiel MailInApp JWT) und eine Kontakt-E-Mail ein und lassen Sie Distribution State auf Local.
- Öffnen Sie API (Enable OAuth Settings) und aktivieren Sie Enable OAuth. Der JWT-Fluss nutzt die Callback URL nie, sie ist aber Pflicht:
https://login.salesforce.com/services/oauth2/successgenügt. - Fügen Sie unter OAuth Scopes Manage user data via APIs (api) und Perform requests at any time (refresh_token, offline_access) hinzu.
- Aktivieren Sie unter Flow Enablement Enable JWT Bearer Flow und laden Sie das Zertifikat (
mailinapp.crt) hoch. Klicken Sie auf Create. - Klicken Sie auf dem Tab Policies der App auf Edit. Setzen Sie unter OAuth Policies Permitted Users auf Admin approved users are pre-authorized und wählen Sie das Profil oder Permission Set des Benutzers, als der sich MailInApp anmeldet. Das macht den Fluss nicht-interaktiv: Ohne diese Einstellung erwartet Salesforce, dass jemand einen Zustimmungsbildschirm bestätigt. Speichern Sie.
- Öffnen Sie auf dem Tab Settings die OAuth Settings und klicken Sie auf Consumer Key and Secret. Salesforce schickt Ihnen per E-Mail einen Bestätigungscode und zeigt dann den Consumer Key: Das ist der Issuer, den MailInApp braucht. Das Secret brauchen Sie nicht.
Der Benutzer, als der sich MailInApp anmeldet, sieht genau das, was dieser Benutzer in Salesforce sieht. Am saubersten ist ein eigener Integrationsbenutzer mit Lesezugriff auf die Objekte, die Ihre E-Mails nutzen. Ein Feld, das für diesen Benutzer verborgen ist (Sicherheit auf Feldebene), fehlt in den Abfrageergebnissen.
In MailInApp verbinden
Gehen Sie zu Datenquellen → + API-Verbindung und tragen Sie ein:
- Endpoint-URL: die Abfrage-URL Ihrer Org mit einer SOQL-Abfrage, zum Beispiel
https://yourorg.my.salesforce.com/services/data/v62.0/query?q=SELECT Name, Amount, StageName, CloseDate, Account.Name FROM Opportunity WHERE IsClosed = false. Sie können die Abfrage mit normalen Leerzeichen schreiben, MailInApp kodiert sie. - Datenpfad:
records. Salesforce liefert die Zeilen in einem ArrayrecordsnebentotalSizeunddone. - Authentifizierung: OAuth2 JWT Bearer, mit:
- Token-URL:
https://login.salesforce.com/services/oauth2/token(oder die Ihrer My Domain,https://yourorg.my.salesforce.com/services/oauth2/token); für eine Sandboxhttps://test.salesforce.com/services/oauth2/token. - Issuer: der Consumer Key der App.
- Subject: der Salesforce-Benutzername, als der sich MailInApp anmeldet.
- Audience:
https://login.salesforce.com(für eine Sandboxhttps://test.salesforce.com). - Privater Schlüssel: der Inhalt von
mailinapp.key.
- Token-URL:
Klicken Sie auf Diese Einstellungen testen: MailInApp holt ein echtes Token, führt die Abfrage aus und zeigt die ersten Zeilen so, wie Ihre Merge-Tags sie sehen. Nach dem Speichern prüft Gespeicherte Verbindung testen sie jederzeit, ohne den Schlüssel erneut einzufügen.
Eine Verbindung ist eine Abfrage. Legen Sie eine pro Aufgabe an: offene Opportunities für eine Pipeline-E-Mail, das Preisbuch für einen Produktkatalog, Kontakte für eine Zielgruppe.
Abfragen mit SOQL
Die Abfrage bestimmt genau, welche Daten Sie bekommen. Wählen Sie nur die Spalten, die Ihre E-Mail braucht.
- Verknüpfte Felder funktionieren. Salesforce liefert ein Beziehungsfeld wie
Account.Nameals verschachteltes Objekt; MailInApp macht daraus ein Feld namensAccount.Name. Schreiben Sie es als{{alias.Account.Name}}in einem Merge-Tag oder als{{Account.Name}}in einem Wiederholungsblock. Das geht bis zu drei Ebenen tief (Account.Owner.Name), und dieattributes-Metadaten, die Salesforce jedem Datensatz anhängt, werden ausgelassen. - Sortieren und begrenzen Sie in der Abfrage.
ORDER BY CloseDateundLIMIT 10bestimmen Reihenfolge und Zeilenzahl eines Wiederholungsblocks. - Bis zu 1.000 Zeilen pro Abruf, genug für einen Digest oder Katalog.
- Bei jedem Rendern frisch abgerufen. Jeder Versand, auch jeder Lauf eines wiederkehrenden Versands, führt die Abfrage erneut aus. Die E-Mail zeigt also immer die aktuellen Salesforce-Daten. Nur das OAuth-Token wird zwischengespeichert.
Einige nützliche Abfragen:
SELECT Name, StageName, Amount, CloseDate, NextStep, Account.Name FROM Opportunity WHERE IsClosed = false ORDER BY CloseDate
SELECT Name, ProductCode, UnitPrice, Product2.Description, Product2.DisplayUrl FROM PricebookEntry WHERE Pricebook2.IsStandard = true AND IsActive = true
SELECT Id, FirstName, LastName, Title, Email, HasOptedOutOfEmail, Account.Name, Account.Industry FROM Contact WHERE AccountId != null
Die Daten nutzen
Fügen Sie die Verbindung einer E-Mail über das Daten-Panel des Studios hinzu, mit einem Alias (zum Beispiel pipeline) und einer Rolle:
- Merge-Felder lösen
{{pipeline.feld}}aus der ersten Zeile auf: eine einzelne Kennzahl. - Zeilen wiederholen speisen einen Wiederholungsblock, der seinen Inhalt pro Zeile wiederholt, zum Beispiel eine Karte pro Produkt.
- Dieselben Zeilen speisen KPI-, Balken-, Linien- und Kreisdiagramme: Eine KPI-Kachel, die
Amountsummiert, ist eine Live-Zahl der offenen Pipeline; ein Balkendiagramm nachStageNamezeigt die Pipeline nach Phase.
Für jeden Empfänger ein anderer Ausschnitt
Zeilen filtern in einem Wiederholungsblock und der Filter eines Diagramms können ein Salesforce-Feld mit den Daten des Empfängers vergleichen. Mit einer Zielgruppenliste mit der Spalte company zeigt die Regel Account.Name ist gleich {{company}} jedem Händler nur seine eigenen Opportunities, aus einer gemeinsamen Abfrage. Die Kopie jedes Empfängers wird beim Versand aus seiner eigenen Zeile gerendert.
Ihre Salesforce-Kontakte importieren
Ihre Zielgruppe ist eine MailInApp-Kontaktliste. Um sie aus Salesforce zu füllen, legen Sie eine API-Verbindung mit einer Contact-Abfrage an (die dritte oben). Gehen Sie dann zu Kontakte → Kontakte importieren und wählen Sie API-Verbindung.
MailInApp liest die Zeilen mit den gespeicherten Zugangsdaten, erkennt die Salesforce-Felder und bietet Salesforce-Zuordnung verwenden an: FirstName → first_name, Account.Name → company, Id → salesforce_id usw. Ein Kontakt, bei dem in Salesforce Email Opt Out (HasOptedOutOfEmail) aktiviert ist, wird im Prüfschritt markiert, der anbietet, ihn auszulassen. Ein als CSV exportierter Salesforce-Bericht wird genauso erkannt. Siehe Leads importieren.
Der Import ist eine Kopie: Starten Sie ihn erneut, um neue Kontakte zu übernehmen.
Ein vollständiges Beispiel finden Sie unter Interaktive E-Mails mit Live-Daten aus Salesforce: ein wöchentlicher Pipeline-Digest aus dieser Verbindung.
