Service Email To Case Configure

Configure Email-to-Case (Metadata API)

Configure Salesforce Email-to-Case entirely through the Metadata API (no Setup UI), for headless org configuration. The skill builds a CaseSettings source file for the desired emailToCase state, then applies it with scripts/apply-casesettings.py, which runs updateMetadata in two phases — the full emailToCase block + Support Settings (Phase A), then routing addresses (Phase B) — and verifies by re-reading. Two phases because a single deploy fails on a fresh org: On-Demand must be live before an address binds (see Rules / Constraints).

Scope

• In scope: Enabling Email-to-Case org-wide and setting its toggles (full field lists in Required Inputs and step 4); creating EmailToCase, Outlook, and GmailOAuth routing addresses; applying the change to an sf-CLI-authenticated org via apply-casesettings.py; verifying by re-reading.
• Out of scope:
• `E2cEasy` routing addresses — created only through the Service Easy Setup wizard, not the Metadata API; route the user there.
• Authenticating the org — the user authenticates out-of-band (e.g. sf org login web); the script reuses that session and never handles passwords or tokens.
• Case object schema, layouts, assignment rules, or Web-to-Case.

Attaching an Agentforce service agent (delegation)

When the user wants an Agentforce Service Agent to answer these emails, configure the Email-to-Case base (the Workflow below), then delegate — this skill never creates or modifies agents.

Gate on org capability first. Attaching an agent needs the org entitled for Agentforce Email-to-Case; that entitlement surfaces as the BotEmailDefinition metadata type, so probe read-only before delegating:

scripts/check-agent-email-capability.sh <target-org-alias>   # pins describe to the org's API version

Exit 3 → not entitled: stop, tell the user, and configure the plain Email-to-Case base only — make no Agentforce agent or channel-wiring changes. Any other non-zero is an unreachable org, not "not entitled" — fix auth and re-run. On exit 0, delegate:

1. Agent creation → `agentforce-generate`, omitting the Service Customer Verification topic (unsupported on the email channel) and including an Escalation subagent so the agent can hand off to a human — on email, escalation transfers the case to a service rep, and without the subagent the agent can't escalate.
2. Wiring → `service-agentforce-channel-configure` Branch C.

Required Inputs

Gather or infer before applying. Ask only when a wrong assumption would produce a broken or incorrect result:

• Target org alias — the sf CLI alias/username of an already-authenticated org. The script obtains the session with sf org display and sf org auth show-access-token; it does not log in for you.
• Routing address(es) — for each: routingName (unique label), addressType (EmailToCase default, or Outlook / GmailOAuth), caseOrigin, and casePriority. The platform rejects the address if caseOrigin or casePriority is missing, so treat all four as required in the source file.
• Customer-facing email address per routing address — ask explicitly for each, in address order; never guess, default, or reuse from earlier context. Not stored in the source file — passed at apply time via --routing-email (one per address; the script fails closed on a count mismatch).
• Support Settings — Default Case Owner & Automated Case User — preserve-first, never assumed:
• Independent, preserved per field. Each configured field is left untouched; change one only if the user asks (--overwrite-support-settings). Ask only for the field(s) unset.
• For each unset field, ask (never default to the authenticated user): Default Case Owner type (User/Queue) + value (active Username or Queue DeveloperName) → --owner-type/--owner-value; Automated Case User type (User/System) — User needs a username, System needs no value → --automated-type/--automated-value (+ optional --system-user-email for System when the org's automated user doesn't exist yet).
• If any value is invalid, the script fails — get a valid value and re-run; never substitute or guess.
• Pass --use-authenticated-user only if the user explicitly asks.
• Case defaults per address (optional) — createTask, saveEmailHeaders, and an optional per-address Default Case Owner (caseOwner + caseOwnerType), opt-in per address (see step 6): omitted by default so cases fall to the org Default Case Owner / assignment rules. When set, caseOwner (active Username or Queue DeveloperName) must be paired with caseOwnerType (User/Queue); the script validates it against the org, failing closed if absent.
• Org-level toggles (optional) — set only if the user asks. Two containers: the `emailToCase` section (enableHtmlEmail, notifyOwnerOnNewCaseEmail, enableE2CDeduplicateAttachments, showWordCountInComposer, plus enableE2CSourceTracking, overEmailLimitAction, unauthorizedSenderAction), and top-level Support Settings (enableDraftEmails — plural element name, a sibling of emailToCase). See step 4's table for container/UI-label mapping; top-level scalar toggles apply in Phase A.

Defaults: enableEmailToCase and enableOnDemandEmailToCase default to true (both required — On-Demand before routing addresses); addressType defaults to EmailToCase. Support Settings have no default — preserved if set, otherwise elicited (never the authenticated user).

Workflow

All steps are sequential.

1. Confirm the org (and its type) — confirm the target org alias is authenticated (sf org display --target-org <alias>). The apply script checks the Organization row and refuses to mutate a production org (non-sandbox, non-trial) unless --confirm-production is passed — enabling Email-to-Case is permanent and org-wide. If production, tell the user and confirm before re-running with --confirm-production. Sandboxes, scratch orgs, and trials deploy without the flag.

1. Elicit the routing email(s) — ask the user for the exact customer-facing email address for each routing address (never assume, default, or carry a value over from earlier). Pass them to the script via --routing-email in the order the addresses appear in the source file.

1. Load the template — read assets/CaseSettings.settings-meta.xml for structure and field placement. Its comments are authoring guidance for you — never copy them into the output. Emit only the elements you set; the output must be comment-free, matching examples/CaseSettings-two-addresses.settings-meta.xml.

1. Enable the E2C switches, then confirm the optional toggles — set both enableEmailToCase and enableOnDemandEmailToCase to true (both required; On-Demand must be on before routing addresses can be created — the script enables it in Phase A before Phase B). Then handle the non-required convenience settings, which the template turns on by default: