forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-email-to-case-configure
service-email-to-case-configure
VerifiedUse to configure Salesforce Email-to-Case headlessly via the Metadata API. Reads CaseSettings, applies the emailToCase config with updateMetadata, and verifies by re-reading. Also the entry point for attaching an Agentforce agent to Email-to-Case: configures the E2C base, then delegates agent creation and channel wiring. TRIGGER on set up/configure Email-to-Case, enable E2C routing addresses, add a routing address, or E2C with an Agentforce agent. DO NOT TRIGGER for the interactive Easy Setup wizard, On-Demand E2C only, general Case/web-to-case setup, or an agent with no E2C involved.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.5 KB |
| assets/CaseSettings.settings-meta.xml | config | 2.5 KB |
| examples/CaseSettings-two-addresses.settings-meta.xml | config | 1.8 KB |
| references/apply-mechanics.md | markdown | 4.8 KB |
| references/routing_address_reference.md | markdown | 7.4 KB |
| references/troubleshooting.md | markdown | 5.1 KB |
| scripts/apply-casesettings.py | script | 65.1 KB |
| scripts/check-agent-email-capability.shexecutable | script | 1.8 KB |
| scripts/tests/__init__.py | script | 0 B |
| scripts/tests/_bootstrap.py | script | 1.5 KB |
| scripts/tests/_fakeorg.py | script | 15.2 KB |
| scripts/tests/_run.py | script | 2.7 KB |
| scripts/tests/test_apply_org_scenarios.py | script | 33.6 KB |
| scripts/tests/test_get_session.py | script | 5.1 KB |
| scripts/tests/test_new_capabilities.py | script | 8.0 KB |
| scripts/tests/test_validate_casesettings.py | script | 7.3 KB |
| scripts/validate-casesettings.py | script | 10.6 KB |
references/troubleshooting.md
View on GitHub# Email-to-Case — Troubleshooting
Full symptom → resolution table for `apply-casesettings.py`. Read this when the apply
or verify step reports an error, or when configured settings don't behave as expected.
| Issue | Resolution |
|-------|------------|
| Routing address fails on a fresh org with a single deploy | Use `apply-casesettings.py` — it enables the toggles (Phase A) before adding addresses (Phase B). A plain `sf project deploy` cannot provision addresses from scratch. |
| Phase B fails: "We couldn't save your routing address... custom email services named EmailToCase" | The On-Demand email service was not provisioned. This happens if the On-Demand toggle was set with a minimal field-level patch instead of writing the complete `emailToCase` block. `apply-casesettings.py` writes the full `emailToCase` block in Phase A specifically to provision it; do not reduce the write to a minimal patch. |
| Apply fails: "The setup requirements for Case Feed Items has to be enabled" | Only happens if the payload includes top-level Case Feed fields (`enableCaseFeed` etc.), which the platform re-validates against Chatter. `apply-casesettings.py` strips all top-level fields it does not own, so it should never hit this. If you see it, confirm the script's `KEEP_TOP_LEVEL_FIELDS` set hasn't been widened to include Case Feed fields. |
| `--routing-email` count doesn't match the addresses | The script exits non-zero without writing. Provide exactly one `--routing-email` per routing address, in the order they appear in the source file. |
| Platform rewrites `routingName` to equal `emailAddress` | Expected for `EmailToCase` addresses. The verify read will show `routingName` == the supplied email; this is the platform's behavior, not an error. |
| Apply fails: "not an active User" / "not a Queue" / "not valid" for owner or automated user | The value the user supplied doesn't exist in the org (or the type is wrong). This is intentional fail-closed behavior — tell the user the value is invalid, ask for a valid Username / Queue DeveloperName / type, and re-run. Do not substitute the authenticated user. |
| Apply/validate fails: "caseOwner is still the placeholder" or "sets caseOwner without caseOwnerType" on a routing address | A per-address Default Case Owner was left half-filled. Either supply a real value **and** its `caseOwnerType` (`User`/`Queue`), or remove both `caseOwner` and `caseOwnerType` from that address to fall back to the org Default Case Owner. The per-address owner is opt-in — omit it unless the user asked for a specific owner. |
| Support settings unexpectedly unchanged | The org already had a Default Case Owner + Automated Case User, so they were preserved (`supportSettings.action: preserved-existing`). Pass `--overwrite-support-settings` only if the user explicitly wants to replace them. |
| Requested address is `GmailOAuth` but org already has one | `GmailOAuth` connectors conflict; do not stack a second. Confirm the existing connector before adding. |
| `E2cEasy` requested via Metadata | Not supported by the Metadata API — direct the user to the Service Easy Setup wizard. |
| New address doesn't receive production mail | For `EmailToCase`, the customer must verify the Salesforce-generated forwarding address out-of-band; `isVerified` is read-only and set by that flow, not by the apply. |
| Org not authenticated / token expired | The script reuses the sf CLI session. Have the user run `sf org login web -a <alias>` (or re-auth) first. |
| Apply exits: "Target org appears to be PRODUCTION" | The safety gate fired. Confirm with the user that they intend to configure Email-to-Case on this production org (it's permanent), then re-run with `--confirm-production`. Do not add the flag without asking. |
| Apply exits: "Could not determine whether this is a production org" | The `Organization` row wasn't readable, so the gate fails closed and treats the org as production. Confirm the org is safe to mutate, then re-run with `--confirm-production`. |
| `--verify-cases` exits non-zero: "No Cases with Origin='Email'" | The inbound test email hasn't been processed yet, the routing address isn't verified, or `--supplied-email` excludes it. The check looks back over `LAST_N_DAYS:3`, so a test email older than that window won't match — send a fresh one. Confirm the user actually sent the email, wait a moment, and re-run. Drop `--supplied-email` if it over-narrows. |
| `--verify-cases` finds a Case but no incoming `EmailMessage` | The Case may have been created another way (not inbound email). Re-run once the inbound email has been processed; proof requires `Incoming=true` linked to the Case. |
| "Enable Email Drafts" toggle silently ignored | The element name is `enableDraftEmails` (plural) and lives at the **top level** of `CaseSettings`, not inside `emailToCase`. A singular name or wrong container is ignored by the platform. |
| An `emailToCase` toggle doesn't take effect | Confirm it belongs in the `emailToCase` section, not top-level. `enableHtmlEmail`, `notifyOwnerOnNewCaseEmail`, `enableE2CDeduplicateAttachments`, and `showWordCountInComposer` are all `emailToCase` children; check the `verified.emailToCase.<field>` value in the JSON summary. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |