Skip to main content

Setup Guide: Salesforce

How to create a Salesforce External Client App and connect it to LettrLabs (verified against a real walkthrough) to trigger mail from CRM data.

A
Written by Adam Rutkowski

Salesforce is one of the most flexible CRMs LettrLabs connects to — it can hold anything from sales Leads and Opportunities to field-service Work Orders. Connecting Salesforce syncs your CRM data into LettrLabs' Data Integration pipeline, so you can automatically trigger printed mail and handwritten cards off real activity in Salesforce (a completed work order, a converted lead, a closed opportunity) instead of exporting lists by hand.

Unlike some LettrLabs connectors, Salesforce connects through OAuth — you'll be sent to Salesforce's own login screen partway through setup, rather than typing a single API key. This guide walks through connecting your Salesforce org, understanding what data syncs, and building your first work-order-triggered mail automation.

Before you start

  • Salesforce administrator access to your org — you'll be creating and configuring an External Client App (Salesforce's current term for what it used to call a Connected App), which requires admin-level Setup access.

  • Know whether you're connecting your Salesforce production org or a sandbox org — the LettrLabs connection form has a separate toggle for this.

  • If you plan to build work-order-triggered mail specifically, Work Orders in your org should have their address fields (street, city, state, postal code) filled in, and be linked to a Contact with a usable name — see the Best Practices article below for why this matters.

Step 1: Create the External Client App

  1. Log in to your Salesforce organization.

  2. Go to Setup (the gear icon in the top right).

  3. In the left sidebar, navigate to Platform Tools > Apps > External Client Apps > External Client App Manager.

  4. Click New External Client App in the top right corner.

Step 2: Basic app info and start page

After creating the app, you'll land on its overview page (Policies tab). Under App Policies, set Start Page to None.

Step 3: Configure OAuth policies

Still on the Policies tab, scroll down and configure:

  • Plugin Policies — Permitted Users: All users can self-authorize; leave OAuth Start URL empty.

  • OAuth Flows and External Client App Enhancements — enable Client Credentials Flow, and set Run As (Username) to a Salesforce user dedicated to this integration.

  • App Authorization — Refresh Token Policy: Refresh token is valid until revoked; IP Relaxation: Relax IP restrictions; leave Enable Single Logout and High Assurance Session Required unchecked; Session Timeout: default (1–1440 minutes).

Step 4: Basic Information (Settings tab)

Go to the Settings tab > Basic Information and fill in:

  • External Client App Name and API Name — anything you'll recognize.

  • Contact Email — your email.

  • Distribution State — Local.

Leave Contact Phone, Info URL, Icon URL, Logo Image URL, and Description empty, then click Save.

Step 5: Configure OAuth settings

  1. Expand OAuth Settings and add each of the following callback URLs on its own line:

    • https://app.lettrlabs.com/data-integrations/oauth/callback (production)

    • https://app-dev.lettrlabs.com/data-integrations/oauth/callback, https://app-qat.lettrlabs.com/data-integrations/oauth/callback, https://app-uat.lettrlabs.com/data-integrations/oauth/callback (non-production environments)

    • http://localhost:3000/data-integrations/oauth/callback (local development only)

    Include every environment you might connect from to avoid a redirect_uri_mismatch error — LettrLabs will only redirect back to the exact URL your organization is running on.

  2. Under OAuth Scopes, move these into Selected OAuth Scopes: Full access (full) and Perform requests at any time (refresh_token, offline_access).

  3. Enable Introspect all Tokens; leave Configure ID token unchecked.

Step 6: Flow enablement and security

  • Flow Enablement — enable Client Credentials Flow and Authorization Code and Credentials Flow; disable Device Flow, JWT Bearer Flow, and Token Exchange Flow.

  • Security — enable Require secret for Web Server Flow; disable Require secret for Refresh Token Flow, PKCE, Refresh Token Rotation, and JWT-based access tokens.

  • Trusted IP Ranges — leave empty.

Step 7: Save the remaining settings

Leave SAML Settings, Canvas App Settings, Mobile App Settings, Push Notification Settings, and Notification Settings all unchecked/disabled, then click Save.

Step 8: Access your Consumer Key and Secret

Go to OAuth Settings and click Consumer Key and Secret.

Step 9: Verify your identity

Salesforce will email you a verification code to confirm it's really you accessing the app's credentials. Check your email, enter the code, and click Verify.

Step 10: Copy your credentials

Copy the Consumer Key and Consumer Secret shown — these are what LettrLabs calls Client ID and Client Secret in the next step. Keep them secure; anyone with these credentials can access your Salesforce data through this app.

Step 11: Connect Salesforce in LettrLabs

  1. From your LettrLabs dashboard, open Automations and find the Salesforce tile among the available Data Integration connectors.

  2. Click the Salesforce tile to open the connection form. Give the connection a Name you'll recognize later.

  3. Enter the Client ID and Client Secret from your Salesforce External Client App.

  4. If you're connecting a Salesforce sandbox org rather than production, check the sandbox option — this changes which Salesforce login URL you're sent to next.

  5. Click Test and Connect. You'll be redirected to Salesforce's own login page (production or sandbox, based on your selection) to log in and approve LettrLabs' access.

  6. After approving, Salesforce redirects you back to LettrLabs, which exchanges the authorization it just received for an access token and begins an automatic connection test.

Step 12: Wait for the connection test

After the redirect back from Salesforce, the connection moves through a short background check:

  • The screen shows a Connecting state while LettrLabs verifies the connection against Salesforce.

  • If the test succeeds, you'll move on to an attribution step (see Step 13).

  • If the test fails, you'll see an error screen. Correct your Client ID/Client Secret or sandbox setting and click Test and Connect again — you don't need to start the External Client App setup over.

Troubleshooting the connection

  • redirect_uri_mismatch — check that the callback URLs in your External Client App (Step 5) match exactly, including the environment you're connecting from.

  • Invalid OAuth state parameter — your session likely expired; just retry.

  • Didn't receive the identity verification email — check your spam folder, or use Resend Code (Step 9).

  • Connection test fails — double-check your Client ID/Client Secret, confirm the Sandbox toggle matches your org type, and make sure the External Client App is Enabled.

Step 13: Attribution setup

Once the connection test succeeds, Salesforce connections ask you to define at which stage a person first becomes a lead, for attribution purposes:

  1. Choose whether attribution is based on your Salesforce Lead or Opportunity object.

  2. Choose the specific stage within that object (for Leads: Open - Not Contacted, Working - Contacted, Closed - Converted, or Closed - Not Converted; for Opportunities: any of Salesforce's standard stages from Prospecting through Closed Won/Closed Lost).

  3. Click Save & Continue.

Note: this attribution setting is about how LettrLabs credits a Lead or Opportunity as originating from a mail touch — it does not limit which Salesforce objects you can build automations against later. Work Order automations (see the Best Practices article) are unaffected by this setting.

Step 14: Activate the integration

Once attribution is saved, click Activate. This is the point where LettrLabs creates the live data connection and Salesforce begins syncing into LettrLabs. Your integration now shows as Active in your list of connections, and an initial sync starts automatically.

Step 15: What syncs from Salesforce

The following Salesforce objects sync into LettrLabs and are available to build automations and filters against:

  • Lead, Contact, Account, Opportunity — your core CRM records.

  • Campaign, CampaignMember — marketing campaign membership.

  • Case — support cases.

  • Work Order — field-service work orders, including their linked Location, Service Territory, and Work Type (Location, Service Territory, and Work Type sync as supporting lookup data used to filter Work Orders — they aren't mailed to directly).

  • LeadHistory, OpportunityFieldHistory, OpportunityContactRole — supporting history/relationship data used for richer filtering and reporting.

Most objects sync incrementally based on when a record was last modified in Salesforce, so updates flow through on later syncs without a full re-pull; the two history streams (LeadHistory, OpportunityFieldHistory) are append-only and sync based on when each history row was created, since those rows are never edited after the fact.

Step 16: Build your first automation

  1. From Automations, start a New Automation and choose your Salesforce integration.

  2. Choose an action (Mail to Recipients or Radius Mail).

  3. Pick the Salesforce object you want to mail off of — for field-service triggered mail, choose Work Order (see the Best Practices article below for details and filter options).

  4. Use the "Find me customers where…" filter builder to narrow which records qualify, choose a card template and cadence, set sending options, choose suppression audiences, and use Calculate Preview to check recipient volume before saving.

Managing and disconnecting

You can disable a Salesforce connection at any time from the integration's menu. Disabling stops the sync; automations built on top of that connection stop pulling new recipients until you reconnect.

Note: the External Client App creation steps above (Steps 1–10) are confirmed against a real Salesforce walkthrough with screenshots, cross-checked against the LettrLabs codebase — including the exact callback URLs and OAuth scopes the connector expects. If Salesforce changes its Setup UI in the future, flag any discrepancy you hit so this guide can be corrected.

Did this answer your question?