Documentation menu

Salesforce

MailInApp doesn't have a Salesforce app to install, and you don't need one. Salesforce's REST API answers plain JSON over HTTPS. MailInApp's API data source with OAuth2 JWT Bearer authentication speaks Salesforce's server-to-server login flow directly: no consent screen, no refresh token to look after, and your Salesforce password never reaches MailInApp.

This guide sets up a read-only connection. It pulls Opportunity, Account, Contact or product rows into merge tags, repeat blocks and live-bound charts, and it can import your Salesforce contacts as an audience. It doesn't write back to Salesforce.

How the connection works

  1. MailInApp signs a short-lived JWT assertion with your app's private key.
  2. It posts that assertion to Salesforce's token endpoint, which checks the signature against the certificate you uploaded and returns an access token. No username or password is sent.
  3. MailInApp caches the access token and calls the Salesforce REST API (a SOQL query) with it, minting a new one before it expires or if a call comes back unauthorized.

Everything happens server-side, on each fetch. Once it's set up there's nothing to keep alive or re-authorize.

Create a key pair

The JWT flow needs an RSA key pair: the certificate goes to Salesforce, the private key goes to MailInApp. If you don't have one, generate a self-signed pair with OpenSSL:

openssl req -x509 -newkey rsa:2048 -nodes -keyout mailinapp.key -out mailinapp.crt -days 730 -subj "/CN=MailInApp"

Keep mailinapp.key somewhere safe. You paste it into MailInApp once, and it's masked from then on.

Set up the Salesforce side

Salesforce now creates new integrations as External Client Apps (new Connected Apps are turned off by default in recent orgs).

  1. In Setup, open External Client App Manager and click New External Client App.
  2. Fill in the name (for example MailInApp JWT), a contact email, and keep Distribution State on Local.
  3. Open API (Enable OAuth Settings) and tick Enable OAuth. The JWT flow never uses the Callback URL, but it's required: https://login.salesforce.com/services/oauth2/success is fine.
  4. Under OAuth Scopes, add Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access).
  5. Under Flow Enablement, tick Enable JWT Bearer Flow and upload the certificate (mailinapp.crt). Click Create.
  6. On the app's Policies tab, click Edit. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized, then select the profile or permission set of the user MailInApp signs in as. This is what makes the flow non-interactive: without it, Salesforce expects someone to click through a consent screen. Save.
  7. On the Settings tab, open OAuth Settings and click Consumer Key and Secret. Salesforce emails you a code to confirm it's you, then shows the Consumer Key: that's the issuer MailInApp needs. You don't need the secret.

The user MailInApp signs in as sees exactly what that user can see in Salesforce. A dedicated integration user with read access to the objects your emails use is the cleanest choice. A field hidden from that user (by field-level security) isn't in the query results.

Connect it in MailInApp

Go to Data Sources → + API connection and set:

  • Endpoint URL: your org's query URL with a SOQL query, for example https://yourorg.my.salesforce.com/services/data/v62.0/query?q=SELECT Name, Amount, StageName, CloseDate, Account.Name FROM Opportunity WHERE IsClosed = false. You can type the query with plain spaces: MailInApp encodes it.
  • Data path: records. Salesforce wraps the rows in a records array next to totalSize and done.
  • Authentication: OAuth2 JWT Bearer, with:
    • Token URL: https://login.salesforce.com/services/oauth2/token (or your My Domain's own https://yourorg.my.salesforce.com/services/oauth2/token); https://test.salesforce.com/services/oauth2/token for a sandbox.
    • Issuer: the app's Consumer Key.
    • Subject: the Salesforce username MailInApp signs in as.
    • Audience: https://login.salesforce.com (https://test.salesforce.com for a sandbox).
    • Private key: the contents of mailinapp.key.

Click Test these settings: it mints a real token, runs the query and shows the first rows exactly as your merge tags will see them. Once saved, Test saved connection re-checks it any time without re-pasting the key.

A connection is one query. Make one per job: open opportunities for a pipeline email, the price book for a product catalog, contacts for an audience.

Querying with SOQL

The query is the data you get back, so select exactly the columns your email needs.

  • Related fields work. Salesforce returns a relationship field like Account.Name as a nested object; MailInApp turns it into a field named Account.Name. Write it as {{alias.Account.Name}} in a merge tag, or {{Account.Name}} inside a repeat block. It works up to three levels deep (Account.Owner.Name), and the attributes metadata Salesforce adds to every record is left out.
  • Sort and limit in the query. ORDER BY CloseDate and LIMIT 10 decide the order and the number of rows a repeat block shows.
  • Up to 1,000 rows per fetch, plenty for a digest or a catalog.
  • Fetched fresh on every render. Each send, including each run of a recurring send, re-runs the query, so the email always shows Salesforce's current data. Only the OAuth token is cached.

Some useful queries:

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

Using the data

Add the connection to an email from the studio's Data panel with an alias (for example pipeline) and a role:

  • Merge fields resolve {{pipeline.field}} from the first row: a single headline figure.
  • Repeat rows feed a repeat block: one copy of its content per row, for example one card per product.
  • The same rows feed KPI scorecard, bar, line and pie charts: a KPI scorecard summing Amount is a live "open pipeline" number, a bar chart grouped by StageName is pipeline by stage.

A different slice for each recipient

A repeat block's Filter rows and a chart's filter can compare a Salesforce field with the recipient's own data. With an audience list that has a company column, the rule Account.Name equals {{company}} shows each retailer only their own opportunities, from one shared query. Every recipient's copy is rendered from their own row at send time.

Import your Salesforce contacts

Your audience is a MailInApp contacts list. To fill it from Salesforce, create an API connection with a Contact query (the third one above), then go to Contacts → Import contacts and pick API connection.

MailInApp reads the rows with the stored credentials, recognizes the Salesforce fields and offers Use Salesforce mapping: FirstName → first_name, Account.Name → company, Id → salesforce_id, and so on. A contact with Email Opt Out (HasOptedOutOfEmail) ticked in Salesforce is flagged in the verification step, which offers to leave them out. A Salesforce report exported as CSV is recognized the same way. See Importing leads.

The import is a copy: run it again to bring in new contacts.

See Interactive Email Powered by Live Salesforce Data for a worked example: a weekly pipeline digest built from this connection.