Troubleshooting the Email Channel
Where to Look First
- Inbound failures rarely produce a user-visible reply because the inbound channel never auto-replies. They show up on the Incident Log instead.
- Outbound failures show up on the conversation as a structured tool error and may also create an Incident Log record.
- Reply-tracking failures tend to be silent — the symptom is that a Scheduled Action never activates. Check the Scheduled Action record and the Incident Log together.
For deeper analysis on any incident, run Debug with AI. For configuration verification, open Agent Runtime Preview.
Inbound Email — Intake
Inbound intake fails quietly by design — the platform never bounces or auto-replies. When something goes wrong, the failure lands in the Incident Log. A routed email reaches the agent whether or not it carries attachments, so it helps to separate two symptoms: the agent never running at all, versus the agent running but not seeing the files.
Symptom: emails arrive at the address but the agent never runs
The channel runs whenever the inbound address matches an active routing record. If nothing happens at all, the cause is in that setup:
1. The Email Service in Salesforce Setup isn’t configured
Inbound mail won’t reach REDA AI unless Salesforce’s Email Services are pointing at the REDA AI handler.
What to check:
- Setup › Email Services — confirm an Email Service is active and uses the REDA AI handler class.
- That at least one Email Service Address is generated and active.
- That Accept Attachments is set to All (binary plus text) if you intend to process attachments.
2. No routing record matches the inbound address
Routing is what turns the channel on for an address. With no matching active routing record, a body-only email is ignored; an email carrying filed attachments records an incident pointing you to the routing setup. Either way, no agent runs.
What to check (REDA AI Admin tab › Operations › Email Routing):
- A routing entry exists for this email. Each entry needs a Label, Email Address, Agent, and Active = on.
- If you see an entry but it’s greyed out, it’s deactivated — click the check icon to reactivate it.
- Matching is exact — either the full address or the part before the
@. Wildcards and domain-level matching are not supported. - The Agent on the routing entry must be an active API-channel agent. Internal, Community, and External Widget agents do not appear in the picker because the email pipeline runs server-side.
Symptom: the agent runs but doesn’t see the attachments
The email reached the agent, but the files you expected aren’t in the conversation. This is about attachment handling, not the channel — the body still went through.
1. Attachment processing is turned off
Email File Processing Enabled is the attachment security control, off by default on a fresh install. With it off, a routed email still reaches the agent as a conversation, but its attachments are ignored — nothing is filed and no incident is recorded.
What to check: turn on Email File Processing Enabled in the REDA AI Admin tab if you want inbound files filed and passed to the agent.
2. The attachments were filtered out
With attachment processing on, two filters silently drop attachments before they reach the agent:
- Attachments smaller than the minimum threshold (~10 KB for binary, very small for text) are skipped as logos and signature images.
- Attachments whose extension isn’t on the Allowed File Extensions Platform Setting are dropped.
If every attachment is filtered, the agent still runs on the email body — it just receives no files. This is by design; logos and stray inline images shouldn’t be treated as documents.
What to check:
- The Allowed File Extensions setting includes the file types the sender is using.
- The actual file sizes — very small files will be filtered as signatures even if they’re legitimate documents.
Symptom: an attachment was processed but the agent failed
When the background email-processing job returns an error, the platform records an incident with the underlying error in the message body, prefixed with the inbound sender and subject for context. The exact label text it uses is “Email file processing failed” with the title “An error occurred while processing the email attachment.”
What to check:
- The Conversation that was created for the run — the assistant message will hold the structured error.
- The Incident Log record — it includes the originating From address and Subject, so you can correlate to a specific inbound email.
- Run Debug with AI on the incident if the error message isn’t self-explanatory.
Symptom: no auto-reply was sent to the sender
This is by design. The inbound channel never auto-replies, never bounces, and never confirms receipt. If you need to acknowledge inbound emails, configure the agent to call an outbound email tool at the end of its run.
Outbound Email — Agent-Sent
Outbound failures surface to the agent as structured tool errors, which show up in the Conversation transcript as the action result.
Symptom: “Failed to send email: …”
This is the verbatim error the agent produces when an outbound send fails. The text after the colon is the underlying Salesforce error.
What to check:
- The text after the colon — that’s the actual cause. Common reasons: deliverability settings (Email Deliverability set to System or No Access), exceeded daily email-with-Apex limit, validation rules on EmailMessage, missing Verified org-wide email address when the agent expects one.
- Setup › Email Administration › Deliverability — confirm the access level allows the running user to send.
- For sandbox orgs, confirm Deliverability is at least System Email Only if the agent is being tested.
Symptom: the email sent but isn’t linked to a Contact or Lead
The agent attempts to resolve the recipient’s email address against Contact and Lead records. When the address matches a single record, the email is linked to that record for activity history. When the address matches more than one record, or none, the email still sends but isn’t linked.
What to check:
- Whether the recipient address exists as the Email field on a single Contact or Lead.
- The running user’s field-level security on the Contact and Lead Email field — the lookup runs in user mode, so denied access fails the lookup silently.
- That the agent passed the email address correctly — lookups are exact-match.
Symptom: the email is sent from the running user’s address, not the brand address
The platform routes through an Org-Wide Email Address only when one is verified and marked “Allow All Profiles”. If no such address exists, the email goes from the running user’s personal address.
What to check:
- Setup › Organization-Wide Addresses — that the brand address is verified.
- That its Allow All Profiles flag is on. If it’s restricted to specific profiles, the platform won’t pick it up.
Symptom: signatures appear inconsistent across users
The agent appends the running user’s configured Salesforce signature when one is set; otherwise it builds a fallback signature from the user’s name, role and email.
What to check:
- Each user’s configured signature in their personal email settings.
- Whether you want a centralised signature instead — in that case, build a custom outbound email tool that uses an Email Template, rather than the built-in send_email tool.
Symptom: large outbound batches stop after a while
Outbound email is regular Salesforce Messaging.SingleEmailMessage, which counts against the daily email-with-Apex governor limit. Once the limit is hit, further sends fail until the limit resets.
What to check: Setup › Email Administration to monitor today’s usage. For high-volume agent fleets, pace outbound work by scheduling actions across the day rather than sending in tight bursts.
Reply Tracking
Reply tracking ties an inbound reply on an agent-sent email back to a pending Scheduled Action and activates it. Failures here are usually silent — the action just doesn’t fire.
Symptom: the recipient replied but the Scheduled Action never activated
Check the master switch first, then these six:
0. Email Reply Tracking is switched off — and it ships off. The Email Reply Tracking platform setting defaults to disabled. It is the very first thing the handler checks on an inbound email, and when it is off the handler returns immediately — so none of the six causes below can even be reached, and nothing is logged to tell you why. Turn it on in REDA AI Administration › Configuration › System & Notifications before troubleshooting anything else.
Reply tracking also requires Enhanced Email to be enabled in the org. Without it,
Salesforce does not create the EmailMessage records the whole mechanism depends on.
1. The reply never landed in Salesforce
Reply tracking depends on inbound replies producing EmailMessage records in Salesforce. If your org doesn’t use Email-to-Case (or another configuration that captures replies as EmailMessage), the reply isn’t visible to the platform and tracking can’t fire.
What to check: whether the inbound reply created an EmailMessage record. If not, the underlying email infrastructure isn’t routing replies into Salesforce.
2. The record-triggered Flow on EmailMessage isn’t configured
The platform doesn’t poll for EmailMessage records on its own. Customers wire a record-triggered Flow on EmailMessage that calls the “Process Inbound Emails” invocable.
What to check:
- Setup › Flows — that the Flow exists, is active, and triggers after a record is created on EmailMessage.
- Its entry condition includes
Incoming = TRUEso outbound EmailMessages don’t fire it. - It calls the Apex Action “Process Inbound Emails” with the triggering record’s Id.
3. The original outbound email wasn’t sent with a group key
Reply tracking only links replies to Scheduled Actions when both calls share a group_key. Without one, the platform has nothing to match.
What to check: the agent’s prompt/configuration to confirm it passes a group_key on both the send_email and the reply-tracked schedule_action calls. The group key is typically the conversation Id, but any consistent string works.
4. The Scheduled Action wasn’t in pending state when the reply arrived
Reply tracking only matches actions that are still pending. If the action was already executed (perhaps by an earlier reply or a timeout fallback), a later reply has nothing to activate.
What to check: the Scheduled Action record’s status. If it’s already moved out of pending, the reply tracking is working — the action just fired earlier than you expected.
5. Subject matching collisions
When the inbound reply doesn’t carry a parent-thread reference, the platform falls back to subject matching (Re: and Fwd: prefixes stripped). If two pending Scheduled Actions share an identical normalised subject, the matcher can’t disambiguate and the reply may activate the wrong action.
What to check: whether outbound emails on the same agent use distinctive subjects. Generic subjects (“Update”, “Following up”) are reply-tracking traps.
6. The user running the Flow doesn’t have access to Scheduled Action records
The matching query runs in user mode. If the user under whom the EmailMessage Flow runs — typically the Automated Process user for Email-to-Case — can’t see the Scheduled Action records, the matching produces no results.
What to check: the Flow-running user’s permission set against the Scheduled Action object.
Symptom: the wrong reply activated the action
Most often this is the subject-collision case above. Either give your outbound emails distinct subjects, or rely on Salesforce’s thread-linking to populate the parent reference (which the matcher prefers over subject).
How to Walk Through an Email Failure
-
Identify which sub-channel.
Inbound intake (conversational or document), outbound agent-sent email, or reply tracking. The diagnosis paths don’t overlap much.
- For inbound: check the Incident Log for the relevant message. Inbound failures rarely surface anywhere else.
- For outbound: open the Conversation transcript and look at the action result on the relevant tool call. The platform’s message will quote the Salesforce error.
- For reply tracking: open the Scheduled Action record and check its status. If still Pending, the matching didn’t happen; the reply was either filtered, not landed, or didn’t match. If Executed, the system is working — the activation already happened.
-
Run Debug with AI.
Multi-turn analysis usually narrows the cause faster than reading the raw error. See Debug with AI.
Frequently Asked Questions
If the agent never runs, the address isn’t routed: confirm the Email Service points at the REDA AI handler and an active routing record matches the address (a body-only email to an unrouted address is dropped without an incident). If the agent runs but the files are missing, that’s attachment handling: Email File Processing may be off (attachments ignored, no incident by design), or the attachments were filtered as too small or a disallowed extension — check the setting is on and the files are on the allowlist.
On the Incident Log record. The platform includes the From address and Subject in the incident message body when it logs an attachment-processing failure, so you can correlate the incident to a specific inbound email.
The full error text includes a colon followed by the underlying Salesforce error. If the agent’s reply truncated it, look at the action result on the Conversation message — the structured tool result holds the complete error.
The matcher prefers the parent-thread reference set by Salesforce’s thread linking. When that reference is present, matching is robust. When it isn’t, the matcher falls back to subject comparison — which is sensitive to subject collisions across pending actions. Distinct subjects per outbound email reduce the failure rate.
Reply tracking depends on inbound replies producing EmailMessage records in Salesforce. Email-to-Case is the most common configuration that does this, but any setup that creates EmailMessage records on inbound works. If your org has no such configuration, reply tracking won’t fire — the platform compiles cleanly and the feature is simply a no-op there.
Configure a verified Org-Wide Email Address in Salesforce Setup with Allow All Profiles enabled. The platform routes through that address whenever it’s available; otherwise it falls back to the running user’s personal address.
Either the file is too small (the platform filters very small attachments to drop logos and signature images), the extension isn’t on the Allowed File Extensions setting, or the file exceeds Max File Size. All three filters are admin-configurable.
No. Routing matches the full address or the local part (before @) only. Wildcards and domain-level matching aren’t supported — create one routing record per address.
Next Steps
Read AI Incident Logs for the underlying record structure, or revisit the relevant channel page: Email Channel — Inbound, Email Channel — Outbound, Email Reply Handling.