`** so it never renders visibly, but still survives quoted replies from HTML-capable email clients. Text-only clients fall back to "Use email headers for threading".
* `mail.setReplyTo(REPLY_TO_ADDRESS)` — routes customer replies back to your forwarding/routing address so Salesforce can ingest them. Without this, replies land in the integration user's personal Salesforce inbox and never reach Email-to-Case.
* `mail.setSaveAsActivity(false)` — OpenCX already wrote the `EmailMessage` record that triggered this send; we don't want Salesforce to create a second one.
* The `SendEmailResult` loop — logs `OpenCxOutboundEmailSender sendEmail failed:` to the Debug Log when a send is rejected (daily limit exceeded, deliverability off, malformed recipient, etc.). Surface these in **Setup → Debug Logs** when diagnosing delivery issues.
**Org-Wide Email Address (recommended for production):** by default the email is sent from the integration user's personal Salesforce address. To send from a branded address like `support@yourcompany.com`, create an Organization-Wide Email Address in **Setup → Email → Organization-Wide Addresses**, verify it, then add this one line before `emails.add(mail)`:
```apex theme={"dark"}
mail.setOrgWideEmailAddressId('0D2XXXXXXXXXXXX'); // Id of the verified OWA
```
Before the outbound email trigger can actually transmit, your Salesforce org needs two one-time settings:
1. **Setup → Email → Deliverability → Access level** must be `All email`. The trial / sandbox default of `System email only` blocks `Messaging.sendEmail()` with `NO_MASS_MAIL_PERMISSION`.
2. The integration user's profile must have **Send Email** enabled (standard on **System Administrator**).
Skip this step at your own risk — the trigger will silently throw on every AI reply and nothing will leave Salesforce.
Salesforce requires **≥ 75% test coverage** on every Apex class and trigger before you can deploy to production. This test class covers all four methods of `OpenSalesforceCaseManagement` plus all five triggers (new case, customer reply, human-agent reply, owner change, outbound email delivery).
Go to **Setup → Apex Classes** and click **New**, or open the **Developer Console** and go to **File → New → Apex Class**. The class name `OpenSalesforceCaseManagementTest` below is an example — you can rename it freely. Paste:
```apex theme={"dark"}
@isTest
private class OpenSalesforceCaseManagementTest {
/**
* Mocks every OpenCX webhook callout with a generic 200 response so
* tests don't hit the real backend and don't depend on Named Credentials.
*/
private class OpenCxCalloutMock implements HttpCalloutMock {
public HttpResponse respond(HttpRequest req) {
HttpResponse res = new HttpResponse();
res.setStatusCode(200);
res.setHeader('Content-Type', 'application/json');
res.setBody('{"success":true}');
return res;
}
}
@isTest
static void sendCaseEvents_sendsWebhook() {
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
OpenSalesforceCaseManagement.sendCaseEvents(new List{ c.Id });
Test.stopTest();
}
@isTest
static void sendCaseReplyEvents_sendsWebhook() {
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
OpenSalesforceCaseManagement.sendCaseReplyEvents(new List{ c.Id });
Test.stopTest();
}
@isTest
static void sendCaseEmailFromHumanAgentEvents_sendsWebhook() {
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
OpenSalesforceCaseManagement.sendCaseEmailFromHumanAgentEvents(new List{ c.Id });
Test.stopTest();
}
@isTest
static void sendCaseOwnerChangedEvents_sendsWebhook() {
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
OpenSalesforceCaseManagement.sendCaseOwnerChangedEvents(new List{ c.Id });
Test.stopTest();
}
@isTest
static void caseTrigger_firesOnInsert() {
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
insert new Case(Subject = 'From trigger', Status = 'New', Origin = 'Email');
Test.stopTest();
}
@isTest
static void customerReplyTrigger_firesOnIncomingEmail() {
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
insert new EmailMessage(
ParentId = c.Id,
Incoming = true,
Subject = 'Customer reply',
TextBody = 'Hello',
Status = '0' // New
);
Test.stopTest();
}
@isTest
static void humanAgentReplyTrigger_firesOnOutgoingEmail() {
// Must match INTEGRATION_USERNAME in OpenCxHumanAgentReplyTrigger.
// If that user doesn't exist in the test org, the trigger early-returns
// and this test passes without exercising the full body.
final String INTEGRATION_USERNAME = 'opencx-integration@yourcompany.com';
List integrationUsers = [
SELECT Id FROM User WHERE Username = :INTEGRATION_USERNAME LIMIT 1
];
if (integrationUsers.isEmpty()) return;
// Run as a NON-integration user so the `CreatedById != integrationUserId`
// guard treats the insert as a human-agent action.
User runner = [
SELECT Id FROM User
WHERE IsActive = true AND Id != :integrationUsers[0].Id
LIMIT 1
];
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
System.runAs(runner) {
insert new EmailMessage(
ParentId = c.Id,
Incoming = false,
Subject = 'Agent reply',
TextBody = 'Hi there',
Status = '3' // Sent
);
}
Test.stopTest();
}
@isTest
static void ownerChangeTrigger_firesOnOwnerUpdate() {
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
List candidates = [
SELECT Id FROM User
WHERE IsActive = true AND Id != :UserInfo.getUserId()
LIMIT 1
];
if (candidates.isEmpty()) return;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
c.OwnerId = candidates[0].Id;
update c;
Test.stopTest();
}
@isTest
static void outboundEmailSender_queuesEmail() {
// Must match INTEGRATION_USERNAME in OpenCxOutboundEmailSender. If that
// user doesn't exist in the test org, the trigger early-returns and
// this test passes without exercising the full body.
final String INTEGRATION_USERNAME = 'opencx-integration@yourcompany.com';
List integrationUsers = [
SELECT Id FROM User WHERE Username = :INTEGRATION_USERNAME LIMIT 1
];
if (integrationUsers.isEmpty()) return;
User integrationUser = integrationUsers[0];
Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
insert c;
Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
Test.startTest();
// Run the EmailMessage insert AS the integration user so CreatedById
// matches integrationUserId inside the trigger.
System.runAs(integrationUser) {
insert new EmailMessage(
ParentId = c.Id,
Incoming = false,
Subject = 'AI reply',
TextBody = 'Hi there',
HtmlBody = 'Hi there
',
ToAddress = 'customer@example.com',
Status = '3' // Sent
);
}
// Assert BEFORE stopTest — Test.stopTest() restores governor counters
// to their pre-startTest state, so Limits.getEmailInvocations() would
// read 0 if checked after.
System.assertEquals(
1,
Limits.getEmailInvocations(),
'Expected OpenCxOutboundEmailSender to queue one email'
);
Test.stopTest();
}
}
```
Salesforce's `HttpCalloutMock` intercepts the `@future` webhook callouts so these tests don't need a live Named Credential or network access. `Test.startTest()` / `Test.stopTest()` flushes the queued `@future` methods synchronously.
**Keep `INTEGRATION_USERNAME` in sync across all three files** — `OpenCxOutboundEmailSender`, `OpenCxHumanAgentReplyTrigger`, and `OpenSalesforceCaseManagementTest`. If they drift, the triggers stop firing for real traffic **and** the test silently skips the main assertion path (the `if (integrationUsers.isEmpty()) return` guard), which can mask the breakage behind a green test run.
Save with **Save** at the bottom, or in the Developer Console use **File → Save** (⌘S on Mac, Ctrl+S on Windows/Linux).
After saving, run the tests: **Setup → Apex Test Execution → Select Tests → `OpenSalesforceCaseManagementTest`**. All tests should pass, and coverage on `OpenSalesforceCaseManagement` + the five triggers will report ≥ 75%.
The five triggers + test class are enough to make the integration *function*. For a production deployment that won't surprise you in week two, also complete the following:
**1. Dedicated integration user.** Don't OAuth as a named human. In **Setup → Users → Users**, clone the System Administrator profile and create a user named `OpenCX Integration`. OAuth as that user. When real humans leave the company and their logins are disabled, the integration keeps working.
**2. Organization-Wide Email Address.** In **Setup → Email → Organization-Wide Addresses**, add `support@yourcompany.com` and verify it (Salesforce emails a verification link — click it from the target inbox). Then add one line to `OpenCxOutboundEmailSender` before `emails.add(mail)`:
```apex theme={"dark"}
mail.setOrgWideEmailAddressId('0D2XXXXXXXXXXXX'); // Id of the verified OWA
```
Without this, outbound AI replies go out from the integration user's personal Salesforce address. Customers see a weird-looking `From:` and spam filters flag it because the sender domain doesn't match your brand.
**3. SPF on your sending domain.** Publish an SPF record on `yourcompany.com` that includes Salesforce:
```
v=spf1 include:_spf.salesforce.com -all
```
Without it, your outbound AI replies land in spam, and inbound forwarded mail to Salesforce can be rejected at the DMARC layer.
**4. DKIM signing.** In **Setup → Email → DKIM Keys → Create New Key**, generate a key for your sending domain and publish the two CNAME records Salesforce gives you. Unsigned outbound mail gets aggressively spam-filtered by Gmail and Workspace.
**5. Case Assignment Rules.** In **Setup → Case → Case Assignment Rules**, define rules that route incoming Cases to the right Queue based on sender domain, routing address, or keywords. This is what makes the "Case Owner = Queue" choice on the Routing Address actually pay off — Queues without rules are just static inboxes.
**6. Email Deliverability.** **Setup → Email → Deliverability → Access level** must be `All email` (not `System email only`). Sandbox / trial defaults block all outbound — your Dev Edition tests will fail here first.
**7. Daily email limits.** `Messaging.sendEmail` to external addresses is capped per org per GMT-day:
| Edition | External email cap / day |
| ------------------------------------ | ------------------------ |
| Developer Edition / trial | 15 |
| Sandbox | typically low, varies |
| Enterprise / Unlimited / Performance | 5,000 |
If production volume exceeds 5,000/day outbound, replace `Messaging.sendEmail` with an HTTP callout to an external ESP (SendGrid, Postmark, Mailgun) via a Named Credential — the trigger structure stays the same, only the sending primitive changes. Most support workloads stay well under the cap and don't need this.
**8. Monitoring.** Turn on **Setup → Debug Logs** for the integration user before any production cutover. The `OpenCxOutboundEmailSender sendEmail failed:` lines captured here are your first signal when deliverability, limits, or deliverability settings regress.
**9. Strengthen the test class with a behavioural assertion.** The supplied test class covers the trigger code paths (enough for Salesforce's ≥ 75% coverage requirement) but the `outboundEmailSender_queuesEmail` and `humanAgentReplyTrigger_firesOnOutgoingEmail` tests gate their assertions on the integration user existing in the test org. In a fresh sandbox that's fine; in a regression-sensitive production deploy, add a `@testSetup` that creates a dummy user matching `INTEGRATION_USERNAME` so the full send path is always exercised. Without this, refactors to the trigger body could regress silently while the test stays green.
**10. Known gaps to track.** These are intentionally out of scope for the baseline trigger but worth queueing as follow-up work:
* **Bounce handling.** Salesforce sets `EmailMessage.IsBounced = true` when the outbound message bounces. OpenCX isn't notified today — a future 6th trigger on `EmailMessage (after update)` should fire a `case_email_bounced` webhook so the dashboard flags the failed delivery.
* **Idempotency.** If Salesforce re-fires the trigger for the same `EmailMessage` (bulk load, recovery), the customer receives duplicate copies. Add a custom boolean `OpenCx_Sent__c` on `EmailMessage` and set it in the trigger after `sendEmail` succeeds; short-circuit on the flag at the top of the loop.
* **Rate limiting.** `Messaging.sendEmail` caps at 5,000/day in Enterprise. At higher volumes, swap the send primitive for an HTTP callout to an external ESP (SendGrid / Postmark / Mailgun) via a Named Credential — the trigger's filter/build logic stays the same.
Send a test email to an address connected to OpenCX. Escalate the conversation (or ask to speak with a human). Within a few seconds:
1. A Case appears in Salesforce with `Case_From__c` set to `opencx`.
2. Reply on the Case from Salesforce.
3. The reply appears as an agent message on the matching session in your [OpenCX Inbox](https://platform.open.cx/inbox).
If any step fails, jump to [Troubleshooting](/integrations/salesforce/troubleshooting).
## How handoff lands in Salesforce
```mermaid theme={"dark"}
flowchart LR
A[Contact emails] --> B{AI can resolve?}
B -- Yes --> C[AI replies by email]
B -- No --> D[Handoff]
D --> E[Salesforce Case created]
E --> F[Rep replies on the Case]
F --> G[Reply syncs to contact inbox]
```
When
handoff triggers, OpenCX:
1. Creates a Salesforce Case with the conversation topic as **Subject** and the AI summary as **Description**.
2. Sets `Case_From__c` to `opencx` so your views and reports can filter to AI-escalated cases.
3. Attaches the full transcript as Case comments.
4. Stores the Salesforce Case ID on the OpenCX session for tracing.
5. When your rep replies on the Case, the webhook fires and OpenCX delivers the reply to the contact's inbox.
6. When the Case is closed, the OpenCX session resolves.
If the same contact re-engages before the Case is closed, OpenCX appends to the existing Case instead of opening a new one.
## Disconnecting
In OpenCX, open the Salesforce integration and click **Disconnect**. Then in Salesforce, delete the Named Credential (`OpenCX_Integration`) and the Apex Trigger/Class you created. Cases created while the integration was active remain untouched.
***
## Related Documentation
Per-channel implementation details for email handoff.
The path for chat, SMS, WhatsApp, and phone channels.
OAuth errors, missing Cases, webhook issues.
Global handoff rules and office hours.