Home / admin / email-to-case-configuration

email-to-case-configuration

Configuring Salesforce Email-to-Case: Standard vs On-Demand mode selection, routing address setup, email threading via Lightning tokens, auto-response rules, attachment limits, and per-address case field defaults.

• v1.2.0
• Salesforce Spring '25+
• Updated 2026-09-12
• Reliability
• Security
• Operational Excellence

• email-to-case
• routing-address
• on-demand-email-to-case
• email-threading
• service-cloud
• case-creation
• auto-response-rules
• case-settings
• routing-address-verification
• email-message

Open the skill folder on GitHub

Email-to-Case Configuration

This skill activates when an admin needs to configure or troubleshoot Salesforce Email-to-Case: enabling the feature, choosing between Standard and On-Demand mode, creating and verifying routing addresses, ensuring customer reply emails thread into the originating case rather than creating duplicates, and setting per-address case defaults and auto-response behavior.

Before Starting

Gather this context before working on Email-to-Case configuration:

• Which Email-to-Case mode is appropriate? On-Demand is the default choice for most orgs. It uses Salesforce-hosted Apex Email Services and requires no locally installed agent. Standard Email-to-Case requires a downloadable Java agent running on a server inside the company firewall; it keeps email traffic internal but adds operational overhead. Choose Standard only if security policy or data residency rules prohibit email routing through Salesforce infrastructure.
• What are the attachment size limits? On-Demand Email-to-Case accepts an inbound message of up to 35 MB in total (body + attachments + HTML). Because MIME transfer encoding inflates a message by up to 33% in transit, the effective attachment ceiling is approximately 25 MB. Messages over the total limit are rejected at the routing address. There is no separate per-attachment cap — 10 MB and 25 MB are the former org-wide totals (pre-Summer '14 and pre-Winter '21 respectively), not current per-attachment rules.
• Is email threading the top priority? Threading is the single most commonly misconfigured behavior. Salesforce puts a thread token in the body and/or subject of outgoing case email — which settings control that depends on whether the org uses Lightning Threading, and the two switch pairs are mutually exclusive (see Core Concepts). When a customer replies, Salesforce reads the token to locate the parent case and adds the reply as an EmailMessage. If the token is stripped by a mail server or a security gateway, useEmailHeadersForThreading is the only thing standing between the org and a new case per reply.
• Are auto-response rules needed? Auto-response rules only fire when the active case assignment rule fires. Confirm an assignment rule is active and will match the cases created by Email-to-Case before configuring auto-response rules.

Questions to Ask Before Configuring

Ask these before opening Setup. Each one has a gotcha behind it, and an agent that skips them produces a settings file that deploys cleanly and silently drops customer mail.

What a proper configuration adds over just switching Email-to-Case on: every channel is a reviewable element in settings/Case.settings-meta.xml rather than an unowned Setup checkbox, ownership is decided once in the assignment rule instead of racing through a shared org-level field, refused mail leaves a trace, and the reply loop is caught by a script before it is caught by the send limit.

Core Concepts

Standard vs On-Demand Email-to-Case

Email-to-Case has two operating modes with distinct infrastructure requirements:

Standard Email-to-Case uses a locally installed Java agent. The agent polls the company mail server, converts inbound emails to cases, and pushes them to Salesforce via the API. Email traffic travels from the customer to the company mail server and remains inside the corporate network — it never routes through Salesforce infrastructure before case creation. This matters for orgs with strict data residency or email content classification requirements. The agent requires a server to run on, must be kept online, and consumes Salesforce API calls for every email processed.

On-Demand Email-to-Case uses Salesforce-hosted Apex Email Services. Salesforce generates a unique routing address in the format [unique-id]@[instance].salesforce.com. The company configures its mail server to forward inbound email from the public support address (e.g., support@company.com) to this Salesforce address. Email content, including attachments, travels through Salesforce's email infrastructure before the case is created. No local agent is required. This is the recommended mode for the majority of orgs.

Size behaviour differs by mode because the enforcement point differs. On-Demand enforces Salesforce's inbound message limit at the routing address: 35 MB total per message, with an effective attachment ceiling of roughly 25 MB once MIME encoding overhead is applied. Standard Email-to-Case receives mail at the company's own mail server, so the first size gate is whatever that server enforces; the agent then creates the case through the API. Do not quote a per-attachment cap for either mode — Salesforce documents a total-message limit, not a per-attachment one.

Email Threading: Two Switch Pairs and a Header Fallback

An outgoing case email carries a thread token in the body, the subject, or both. Which elements control that depends on the org's threading mode, and the Metadata API guide is explicit that the two pairs are mutually exclusive:

Setting the pair that does not apply to the org changes nothing at all. useEmailHeadersForThreading is the second chance when a mail gateway has stripped the token, and is the one switch worth turning on in every org. Do not verify threading on EmailMessage.ThreadIdentifier: the Object Reference states that field "is not used by On-Demand Email-to-Case". Verify on EmailMessage.ParentId — query in references/metadata-examples.md.

When a customer replies, Salesforce's inbound processing inspects the reply for a matching token. If found, the reply is appended to the originating case as a new Email Message record. If not found, a new case is created. Threading failures occur when:

• The mail server or security gateway strips or modifies the reference string in the body or subject.
• The customer uses a mail client that strips quoted content (removing the body token) AND modifies the subject line (removing the subject token).
• The routing address is misconfigured and inbound mail is not matched to the correct Email-to-Case configuration.

Always test threading end-to-end before go-live: send an inbound email, confirm case creation, reply from the case in Salesforce, have the reply delivered to the customer's inbox, and reply back. The reply must add an Email Message to the original case, not create a new case.

Routing Addresses

A routing address is a per-mailbox Email-to-Case configuration record. Each routing address defines:

• The external email address customers use (emailAddress — the address your mail server forwards from).
• The Salesforce-generated target address (On-Demand mode only) that the mail server forwards to.
• Default values applied to cases created via this address: Case Origin, Status, Priority, and optionally a queue or owner. casePriority is not skippable — the org rejects an address without it (gotchas #15).
• The record type new cases land on, via newEntityRecordType — Case.<DeveloperName>, API 64.0 and later only (gotchas #14). This is the only deterministic record-type control on the channel; keepRecordTypeOnAssignmentRule does not cover it.
• Whether an auto-response is sent and which auto-response rule entries apply.

An org can have multiple routing addresses, one per inbound support channel (e.g., support@, billing@, returns@). Each address creates cases with its own defaults, allowing cases to be pre-classified by channel before assignment rules run.

Two fields are read-only and never come from your source file: emailServicesAddress (the Salesforce-generated address the mailbox forwards to) and isVerified. A freshly deployed routing address therefore always lands unverified, and Salesforce accepts no mail at it until someone clicks the verification link in the org.

What the address stamps on the Case, and what it does not. caseOrigin sets Case.Origin, casePriority sets Case.Priority, and caseOwner + caseOwnerType reach Case.OwnerId — but by writing the single org-level defaultCaseOwner, so only one address can use them meaningfully. There is no routing-address field on Case at all; the address is recorded one object over as EmailMessage.EmailRoutingAddressId. That makes Case.Origin the only per-channel hand-off an assignment rule can read, which is the rule design shown in references/metadata-examples.md.

Auto-Response Rules and Assignment Rule Dependency

Auto-response rules send confirmation emails to customers when cases are created. They are not independent: an auto-response rule entry fires only when the active case assignment rule fires for the same case creation event. If no assignment rule is active, or if no rule entry matches the incoming case, the auto-response will not fire regardless of auto-response rule configuration.

This dependency is the most commonly misdiagnosed "auto-response not sending" issue.

Common Patterns

Pattern: On-Demand Email-to-Case with Verified Threading

When to use: Configuring Email-to-Case for the first time in an org with no local email agent requirement.

How it works:

1. Navigate to Setup → Email-to-Case. Click Edit and enable Email-to-Case. Select "Enable On-Demand Service" to activate On-Demand mode.
2. Save. Return to Email-to-Case settings. Under Routing Addresses, click New.
3. Enter the routing address name (for display), the email address customers use (e.g., support@company.com), and the default Case Origin, Status, and Priority for cases created from this address.
4. Save the routing address. Salesforce generates a Salesforce-hosted email address. Copy this address.
5. Configure the company mail server to forward inbound mail from support@company.com to the Salesforce-generated address.
6. Click "Send Verification Email" on the routing address to confirm Salesforce can receive at that address. Verify the address in the confirmation email.
7. Test threading: send an email to support@company.com, confirm a case is created in Salesforce, send a reply from the case, deliver it to an inbox, and reply back. The reply must append to the original case as an Email Message, not create a new case.

Why not Standard Email-to-Case: Standard requires a local agent, server maintenance, and consumes API calls per email. On-Demand is fully hosted and requires only a mail forwarding rule.

Pattern: Multiple Routing Addresses for Channel-Based Case Classification

When to use: The org has multiple inbound support email addresses (e.g., billing, technical, returns) and needs cases created from each address to have different default fields or route to different queues.

How it works:

1. Create one routing address per inbound channel, each with appropriate default Case Origin, Status, and Priority.
2. In the case assignment rule, add rule entries that match on Case Origin (or a custom field set by the routing address) and route to the appropriate queue.
3. Each address generates its own Salesforce-hosted routing address (On-Demand). Configure a separate forwarding rule on the mail server for each address.
4. Test each channel independently to confirm cases arrive with correct defaults.

Why not a single routing address with automation: A single address cannot set per-channel defaults natively. Using multiple addresses keeps classification at the point of creation rather than requiring post-creation automation.

Decision Guidance

Recommended Workflow

1. Read the org before writing anything. sf project retrieve start --metadata "Settings:Case" "AssignmentRules:Case" "AutoResponseRules:Case". routingAddresses is a full-replacement list, so every later edit must start from what the org actually has (references/gotchas.md #7).
2. Answer the seven questions above and fill in templates/email-to-case-configuration-template.md: channels, the caseOrigin value each stamps, the owning queue, the acknowledgement sender, the threading mode. Confirm the mode choice — On-Demand unless data residency policy forbids it.
3. Shape the metadata from references/metadata-examples.md: the emailToCase block with one routingAddresses element per channel, the matching Case.assignmentRules entries keyed on Case.Origin, and the package.xml naming Settings:Case explicitly (the wildcard does not work for an individual setting).
4. Run the checker — python3 scripts/check_email_to_case_configuration.py --manifest-dir <dir> --verbose. It exits 1 on ERRORs only; add --strict to fail on the advisory WARNs too. Clear every ERROR (duplicate emailAddress, caseOwner without caseOwnerType, more than one address setting caseOwner, auto-response sender equal to a routing address, E2C-PRI-01 a missing casePriority, E2C-RT-01 a bare newEntityRecordType, E2C-RT-02 that element on a package.xml below API 64.0). Justify or fix each WARN — isVerified reports org state that metadata cannot set at all.
5. Deploy, then finish the setup that metadata cannot do: copy each emailServicesAddress out of Setup, create one forwarding rule per channel, disable any auto-reply on the forwarding mailbox, send the verification email, and confirm each address reads Verified. The checklist is in references/metadata-examples.md.
6. Run the three tests from references/metadata-examples.md: the threading round-trip through the production mail gateway asserted on EmailMessage.ParentId, the routing-address/origin query, and the loop test (one email per address, case count must stop at one).
7. Hand over. Record the public address to emailServicesAddress mapping, the verification dates, and the threading mode in the org runbook — the org will not hand emailServicesAddress back if an address is ever deleted. Work through the Review Checklist below.

Review Checklist

Run through these before marking Email-to-Case configuration complete:

• [ ] Email-to-Case feature is enabled in Setup and mode (On-Demand vs Standard) is documented and justified
• [ ] Each routing address has the external email address, default Case Origin/Status/Priority, and a verified Salesforce-hosted target address (On-Demand) or agent configuration (Standard)
• [ ] Mail server forwarding rules are active and tested: inbound email to each support address reaches Salesforce and creates a case
• [ ] Email threading tested end-to-end: customer reply to a case email adds an Email Message to the original case and does not create a new case
• [ ] Active case assignment rule exists with at least one entry matching Email-to-Case–created cases; catch-all entry routes remaining cases to a queue rather than default owner
• [ ] If auto-response rules are configured: assignment rule fires for the same case creation events; auto-response rule entry has a valid email template and a sender address that is not the routing address (to prevent email loops)
• [ ] Attachment size limits communicated to support team: On-Demand accepts up to 35 MB total inbound message size, i.e. roughly 25 MB of attachments after MIME encoding overhead; there is no per-attachment cap
• [ ] settings/Case.settings-meta.xml was retrieved from the target org before editing, and the routing-address count in the file to be deployed is not lower than the count in the org
• [ ] At most one routing address sets caseOwner, and it sets caseOwnerType alongside it; per-channel ownership is expressed as caseOrigin plus assignment rule entries
• [ ] Every caseOrigin value used by a routing address exists and is active in the Case.Origin picklist
• [ ] Only the threading switch pair matching the org's threading mode is set; useEmailHeadersForThreading is on
• [ ] unauthorizedSenderAction and overEmailLimitAction are a deliberate choice, and Discard is used only where someone has signed off on losing the message
• [ ] saveEmailHeaders is true on every routing address
• [ ] Every routing address carries casePriority, the value is a deliberate starting tier for that channel, and nothing downstream derives priority behind a "is blank" guard
• [ ] If newEntityRecordType is used: every value is Case.<DeveloperName>, the record type is active on Case, and the package.xml <version> is 64.0 or later
• [ ] Threading verified on EmailMessage.ParentId, not on ThreadIdentifier (blank for On-Demand Email-to-Case by design)
• [ ] python3 scripts/check_email_to_case_configuration.py --manifest-dir <dir> --verbose reports zero ERRORs and every WARN is justified

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. The On-Demand size limit is per-message, not per-attachment — and the number you remember is probably a retired one — Salesforce rejects an inbound On-Demand message once the total (body + attachments + HTML) exceeds 35 MB. MIME transfer encoding inflates the payload by up to 33%, so the practical attachment budget is about 25 MB. 25 MB was the org-wide total before Winter '21 and 10 MB was the total before Summer '14; both numbers survive in older blog posts and in model memory as fictitious per-attachment caps. Quote 35 MB total / ~25 MB effective, and never promise a per-attachment threshold.
2. Routing address verification is required before inbound email is accepted — Until the routing address is verified (by clicking the link in the Salesforce-sent verification email), Salesforce will not accept inbound email at that address. Forwarding can be configured on the mail server before verification, but emails will bounce or be dropped until verification completes.
3. Auto-response rule loops when From address equals routing address — If the auto-response rule is configured to send from the same email address that the routing address is configured to receive at (e.g., both are support@company.com), the auto-response email will arrive back at Salesforce and create another case, which triggers another auto-response, creating an infinite loop. Always use a different From address or a no-reply address for auto-response rules.
4. Lightning thread token stripping by security gateways — Corporate email security gateways (e.g., Proofpoint, Mimecast) sometimes strip or modify the reference string in the email body or subject line as part of link-rewriting or content inspection. This silently breaks threading. Test the full round-trip through the production mail gateway before go-live, not just against a direct SMTP relay.
5. Standard Email-to-Case agent consumes API calls — The local agent converts each email to a case via the Salesforce API. High-volume inbound mail can exhaust the org's daily API call limit. Monitor API usage after go-live if using Standard mode in a high-volume environment.
6. caseOwner is an org-level field wearing a per-address costume — the Metadata API guide states that setting it on a routing address writes CaseSettings.defaultCaseOwner. Give a second address its own owner and the first one's is overwritten, with no deploy warning. Route on Case.Origin instead.
7. Deploying a partial settings file deletes the channels it omits — routingAddresses is a full-replacement list, and emailServicesAddress is read-only, so a deleted address cannot be restored to its old Salesforce-generated value. Always retrieve first.
8. Discard is genuinely silent — both unauthorizedSenderAction and overEmailLimitAction accept it, and a discarded message produces no Case, no EmailMessage and no bounce. Nobody can prove the customer wrote in.
9. newEntityRecordType is version-gated and object-qualified, and the guide says neither — a bare <newEntityRecordType>Support</newEntityRecordType> fails with In field: newEntityRecordType - no RecordType named Support found even when that record type exists and is active; Case.Support resolves. The element itself is rejected below API 64.0 with Property 'newEntityRecordType' not valid in version 63.0, so the package.xml <version> must be raised with it. The field's guide entry (api_meta L112078) carries no version note, unlike fallbackQueue (56.0) and isPermsetControlled (61.0) beside it. UNVERIFIED (2026-09-12): both proven live, not in the guide. Detail in references/gotchas.md #14.
10. casePriority is required by the org and optional in the guide — an address without it is rejected with EmailToCaseRoutingAddress[support@acme.example]: Missing casePriority, though api_meta L112039 marks the field neither Required nor Optional. UNVERIFIED (2026-09-12): proven live. The consequence outlives the deploy: every email case is created with Priority already set, so a null-guarded priority stamp downstream never fires. Detail in references/gotchas.md #15.

Deeper treatment, with the platform behaviour behind each, in references/gotchas.md (15 entries).

Output Artifacts

Reference Files

Related Skills

• admin/case-management-setup — the wider case layer (queues, escalation, entitlements, Web-to-Case); this skill closes that skill's open "routing-address to queue mapping" question via Case.Origin
• admin/assignment-rules — the Case.assignmentRules and Case.autoResponseRules files themselves: criteria grammar, entry order, and the senderEmail this skill must never let equal a routing address
• admin/email-templates-and-alerts — org-wide email addresses and the Classic templates an auto-response entry points at
• admin/queues-and-public-groups — references/queue-behaviour-matrix.md, the email / doesSendEmailToMembers pair that stacks with notifyOwnerOnNewCaseEmail
• admin/business-hours-and-holidays — the SLA clock that starts when an inbound email creates the case
• admin/email-service-inbound — a different feature: Apex Email Services with Messaging.InboundEmailHandler, for inbound mail that must run custom code. On-Demand Email-to-Case is Salesforce's own hosted email service and needs no handler; write one only when case creation is not what you want
• admin/case-feed-send-email-action — the outbound half: the Send Email quick action agents reply from, and its own file limits
• admin/email-deliverability-strategy — SPF, DKIM and DMARC on the domain that forwards into the routing address
• admin/omni-channel-routing-setup — pushing the created case to an available agent; routingFlow and fallbackQueue on a routing address are the entry point
• admin/permission-set-architecture — the grants that isPermsetControlled requires before it stops locking everyone out

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/email-to-case-configuration-template.md
• scripts/check_email_to_case_configuration.py