Skip to content

forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-email-to-case-configure

service-email-to-case-configure

Verified

Use 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.

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. |
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall