> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.supersend.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Salesforce Integration Setup

# Salesforce Integration Setup

## Purpose

Connect your Salesforce org to SuperSend so campaign activity — email sent, opens, and replies — appears on the matching **Contact** in Salesforce.

You connect using an **External Client App** in your own Salesforce org (App Manager → **New External Client App**). Paste its **Consumer Key** and **Consumer Secret** into SuperSend, then authorize with **Connect to Salesforce**. No SuperSend package install is required.

> **Important:** Create an **External Client App**, not a legacy Connected App. Most orgs no longer offer **New Connected App**. SuperSend still uses **Consumer Key** and **Consumer Secret** from that app.

> **Terminology:** In Salesforce OAuth APIs you will see **Consumer Key** and **Consumer Secret** (client ID / client secret). The app type you create is an **External Client App**.

## How the integration works

When a contact in SuperSend matches a Salesforce **Contact** by email address:

- **Email sent** — logged on the Contact (as an email message or task, depending on your org)
- **Email opened** — logged when opens sync is enabled
- **Email replied** — logged when a reply is received

SuperSend does not create new Salesforce Contacts automatically. Events only sync when a Contact with the same email already exists in Salesforce.

At the team level, SuperSend:

1. Saves your External Client App credentials (encrypted).
2. Runs OAuth and token refresh using **your** app.
3. Syncs activity for campaigns where Salesforce is enabled.

## Prerequisites

- **SuperSend:** Org admin access (Admin Settings → Integrations).
- **Salesforce:** Admin who can create External Client Apps (typically System Administrator).
- **My Domain** enabled in Salesforce (most modern orgs have this).
- **Browser:** Allow popups for SuperSend when you click **Connect to Salesforce**.

## Step 1: Create the External Client App in Salesforce

1. Log into your Salesforce org as an admin.
2. Go to **Setup** → search **App Manager** in Quick Find → open **App Manager**.
3. Click **New External Client App** (top right).

   > If your org still shows **New Connected App** instead, see [Legacy Connected App (older orgs)](#legacy-connected-app-older-orgs).

4. Fill in **Basic Information** (labels may vary by release):

   - **External Client App Name:** `SuperSend`
   - **API Name:** `SuperSend` (or accept the default)
   - **Contact Email:** your admin email
   - **Distribution State:** Local (stays in your org only)

5. Open the **Settings** tab (or **API (Enable OAuth Settings)**) and configure OAuth:

   - **Callback URL** — add this exact URL (production SuperSend customers use one line only):

     ```
     https://api.supersend.io/v1/salesforce/oauth/callback
     ```

   - **OAuth Scopes** — add **Manage user data via APIs (`api`)** and **Perform requests at any time (`refresh_token`, `offline_access`)**.

   - **Security** (enable all that apply):

     - Require Proof Key for Code Exchange (**PKCE**) — SuperSend sends PKCE on authorize
     - Require Secret for Web Server Flow
     - Require Secret for Refresh Token Flow

6. Click **Create** or **Save**. Changes can take up to **10 minutes** to propagate.

## Step 2: Configure app policies

1. In **App Manager**, find your **SuperSend** app.
2. Open the app → **Policies** (or **Manage** → **Edit Policies**).
3. Set:

   - **Permitted Users:** `All users may self-authorize` (or your org policy)
   - **IP Relaxation:** `Relax IP restrictions` (unless security requires stricter)
   - **Refresh Token Policy:** `Refresh token is valid until revoked`

4. Save.

## Step 3: Get Consumer Key and Consumer Secret

1. Open **Settings** / **OAuth Settings** on the same External Client App.
2. Copy **Consumer Key** and **Consumer Secret** (some orgs require **Manage Consumer Details** + email verification first).

   > Treat these like passwords. They grant OAuth access to your org.

## Step 4: Connect Salesforce in SuperSend (team level)

1. Go to **Admin Settings** → **Integrations** (`tab=integrations`).
2. Select your **team** from the dropdown.
3. On **Integration Library**, find **Salesforce** → **Add** (or open existing setup).
4. Under **Step 1 — Salesforce app credentials**, paste **Consumer Key** and **Consumer Secret**.
5. Click **Save App Credentials**. Confirm the **Credentials saved** indicator.
6. Wait at least **10 minutes** after creating the app in Salesforce if this is the first save.
7. Under **Step 2 — Authorize SuperSend**, leave **Sync campaign activity to Salesforce** enabled.
8. Click **Connect to Salesforce**. Sign in to the **same org** where you created the app and approve access.
9. When the popup closes, Salesforce shows as connected in the Integration Library.

### Clear or rotate credentials

- **Clear Saved Credentials** — removes saved keys; you must save again before connecting.
- **Rotate** — reset Consumer Secret in Salesforce, then **Save App Credentials** with the new pair.

Consumer Key and Secret are stored encrypted and are not shown again after save. Audit events: `salesforce.byo_credentials_set`, `salesforce.byo_credentials_cleared`.

## Step 5: Enable Salesforce on a campaign

Team connection does not enable sync on every campaign automatically.

**Option A — Campaign Integration Matrix (bulk):**

1. **Admin Settings → Integrations** → **Campaign Integration Matrix**.
2. Select the same **team**.
3. In the **Salesforce** row, enable the integration per campaign.

**Option B — Inside a campaign:**

1. Open the campaign → **Settings** → **Integrations**.
2. Turn on **Salesforce**.
3. Configure toggles:

   - **Enabled** — master on/off
   - **Sync Activity to Salesforce Contacts** — sends, opens, replies
   - Per-event toggles for **email sent**, **replies**, and **opens** when shown

## Expected result

- **Integration Library** shows Salesforce connected for your team.
- For enabled campaigns, activity appears on matching Salesforce Contacts after events in SuperSend.
- Replies and sends appear on existing Contacts with the same email.

## Troubleshooting

- **Connect to Salesforce** disabled or “Complete Step 1 (save credentials) before connecting.”  
  **Fix:** Save valid Consumer Key and Secret in Step 1 first.

- **OAuth fails immediately / integration not configured.**  
  **Fix:** Retry in a few minutes; contact SuperSend support if it persists.

- **`OAUTH_EC_APP_NOT_FOUND` or app-not-found.**  
  **Fix:** Wait 10–15 minutes for Salesforce propagation. Confirm keys in SuperSend match Salesforce. Use External Client App in your org (not the legacy SuperSend package path).

- **`invalid_client_id` / `invalid_client`.**  
  **Fix:** Re-copy Consumer Key/Secret from Salesforce and **Save App Credentials** again.

- **`redirect_uri_mismatch`.**  
  **Fix:** Callback URL must include `https://api.supersend.io/v1/salesforce/oauth/callback` exactly (one line per URL). Ask support for custom or white-label domains.

- **OAuth scope error.**  
  **Fix:** App must include `api` and `refresh_token` / `offline_access`.

- **“You are not allowed to access this app.”**  
  **Fix:** **Permitted Users** must allow self-authorize (or pre-authorize your user).

- **Only see New Lightning App, not External Client App.**  
  **Fix:** Use a System Administrator or ask your Salesforce admin to create the app.

- **Connected but no activity in Salesforce.**  
  **Fix:** Enable Salesforce on the campaign (matrix or campaign Settings). Confirm a Salesforce **Contact** exists with the **same email**. Confirm sync and event toggles are on.

- **Production vs sandbox mismatch.**  
  **Fix:** Create the External Client App and sign in during **Connect** in the same environment (production `login.salesforce.com` vs sandbox `test.salesforce.com`).

- **Popup blocked.**  
  **Fix:** Allow popups for `app.supersend.io` (or your white-label URL), then connect again.

- **Need to reconnect after revoking access in Salesforce.**  
  **Fix:** Disconnect in SuperSend if available, then **Add** again → save credentials → **Connect to Salesforce**.

## Legacy Connected App (older orgs)

Some orgs still offer **New Connected App** instead of **New External Client App**. SuperSend uses the same OAuth flow and the same Consumer Key/Secret fields in Step 1.

| | **External Client App** | **Connected App (legacy)** |
|---|---|---|
| **Create** | **New External Client App** | **New Connected App** |
| **OAuth** | Settings tab | Enable OAuth Settings |
| **SuperSend** | Same callback, scopes, PKCE, Step 1 paste | Same |

Use the same callback URL, scopes (`api`, `refresh_token`, `offline_access`), PKCE, and policies as Steps 1–3 above.

## Legacy SuperSend package (not in app today)

SuperSend previously offered a **managed package + global OAuth** path. That UI is **hidden** until SuperSend’s Salesforce partner setup is complete. Use the External Client App steps in this article.

## Related Articles

- [Integrations Overview](https://help.supersend.io/en/article/integrations-overview-r3pvl9/)
- [HubSpot Integration Setup](https://help.supersend.io/en/article/hubspot-integration-setup-19rap4k/)
- [SuperSend → Make → Salesforce Setup](https://help.supersend.io/en/article/supersend-make-salesforce-setup-dv6sj/) (webhooks — different from native OAuth)