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/apply-mechanics.md
View on GitHub# Email-to-Case Apply Mechanics (why the write is shaped this way)
Load-bearing design rationale behind `apply-casesettings.py`. Read this before changing
how the script builds or sequences its `updateMetadata` payloads. Do not substitute a
plain deploy or a minimal patch.
## Why two phases (and not a single file-based deploy)
Enabling On-Demand Email-to-Case provisions the org's internal email-service
infrastructure, and a routing address can only bind to that infrastructure in a
**subsequent** operation. A single file-based deploy (`sf project deploy`) that both
enables On-Demand and declares a routing address **fails on a freshly-configured org** —
verified on clean orgs. `apply-casesettings.py` therefore reads current settings, applies
the **complete `emailToCase` block** (toggles) plus Support Settings in one `updateMetadata`
call (Phase A), then re-reads and appends routing addresses in a second call (Phase B).
## Two load-bearing properties of the write
- **Send the whole `emailToCase` block, not a minimal patch.** Provisioning the On-Demand
email service is driven by writing the full `emailToCase` block. A minimal field-level
patch that just flips `enableOnDemandEmailToCase` to `true` does **not** trigger
provisioning, so Phase B then fails with "We couldn't save your routing address... custom
email services named EmailToCase." (Verified from scratch on a clean org.)
- **Send only the top-level fields this skill owns; strip the rest.** The platform
re-validates any top-level `CaseSettings` field present in the payload, even at an
unchanged value — and several (notably Case Feed) carry dependencies unrelated to
Email-to-Case (Case Feed re-validation requires Chatter). `apply-casesettings.py` writes
only the fields it sets (`emailToCase`, `enableDraftEmails`, and Support Settings) and
drops every other top-level field, which keeps its current org value via field-level
merge. This is why the skill needs **no Chatter prerequisite** and does not fail on
unrelated org Case configuration. (Verified from scratch on a Chatter-off org: stripping
all other top-level fields still provisioned and bound a routing address, and the omitted
fields — e.g. `enableCaseFeed` — kept their values.)
This is the validated mechanism; do not substitute a plain deploy, do not reduce the
`emailToCase` write to a minimal patch, and do not echo the full record back verbatim.
## Support Settings are preserved per field, via field-level merge
Default Case Owner (`defaultCaseOwner` / `defaultCaseOwnerType`) and Automated Case User
(`defaultCaseUser` / `useSystemUserAsDefaultCaseUser`) are **independent** top-level
`CaseSettings` fields — an org can have one configured and the other not. Because top-level
fields merge at the field level (an omitted field keeps its current org value), the script
**preserves a configured field by simply not emitting it** in the payload, and writes only
the field(s) that are unset (or that the caller explicitly overwrites with
`--overwrite-support-settings`). It therefore requires — and validates — input **only** for
the field being written; supplying a value for an already-configured field without the
overwrite flag leaves the existing value untouched. This is why a single "both configured?"
gate is wrong: on a partially-configured org it would either demand the already-set value or
silently overwrite it. `apply_support_settings` branches the owner and automated-user fields
separately for exactly this reason.
## Routing-address ordering (multi-address preservation)
The `updateMetadata` call **replaces the `routingAddresses` collection wholesale**.
An already-provisioned address is **dropped** if a brand-new address follows it in
document order. Therefore the script **emits new addresses before** the carried-over
existing ones, so existing addresses always survive.
The platform-managed read-only fields (`emailServicesAddress` / `isVerified`) do **not**
affect this — only document order does. As defensive hygiene the script still strips those
read-only fields from the payload (the platform mints them), but stripping is not the
preservation mechanism; ordering is. A runtime **preservation guard** baselines the
expected address count (`initial address count + created count`) captured before Phase A and
**fails the run loudly** if any existing address is dropped anyway.
## API version derivation
The Metadata API version is `max(org apiVersion, 67.0)` — derived from the org and floored
at the skill's `minApiVersion` (`67.0`). This keeps every field the skill sets valid while
auto-adopting newer org features (e.g. a v68+ org that supports the `botEmailDefinition`
binding for Agentforce for Service on Email is picked up automatically). It never claims a
version the org doesn't report. `--api-version` forces a specific value.
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: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |