Email troubleshooting

Fix common email channel issues — connection test failures, missing AI replies, and unwanted auto-replies.

Before debugging, have these ready: your mail host (Gmail, M365, …), the channel status in your OpenCX dashboard, and a recent message or ticket ID if available.

Looking for setup steps? See Connect Email. For routing logic and session matching, see Email Flow.

Common Troubleshooting Scenarios

Symptom	Likely cause	What to do
Pending a long time	Rule not delivering to [e-mail], or filters blocking the test	Send a manual message to your support address and verify a copy reaches the forward destination.
Failed after ~5 minutes	Inbound never showed your registered address in To	Inspect headers (BCC-only paths may not match). Fix the rule, then re-run the wizard test.
AI replies to automated or out-of-office emails	Auto-replies and notifications are forwarded alongside real mail	Block the sender in Blocked Contacts — add known noreply@ and do-not-reply@ domains proactively.
Customer receives duplicate AI replies	Customer sent multiple messages before the first AI reply arrived	Each new message triggers a separate response. Ask customers to wait for the first reply before sending follow-ups. If duplicates persist on single messages, contact support.

If the connection test stays Pending or ends Failed, the problem is almost always forwarding or headers — not a platform outage on our side.

AI Not Replying — Checklist

Work through in order. Stop at the first match.

1. Autopilot disabled — Enable it for email under Autopilot settings.
2. Helpdesk permissions — If you use Zendesk or HubSpot, verify the AI user has full agent permissions (not Contributor or Light).
3. Provider rejected the message — Check your helpdesk logs for delivery warnings or invalid-comment flags.
4. Blocked contact or domain — Confirm the sender is not on your blocklist.
5. AI chose not to reply — Low-confidence answers, prohibited topics, and human-assigned sessions do not produce an outbound email.

What Each Message Must Include

Messages that don’t meet these requirements are silently skipped.

New emails

The To field must contain the support address you registered in the dashboard (e.g. [e-mail]).

Replies to existing threads

Must come from the same sender as the original email and include the session token — either [12345] in the subject or Ref: #12345 in the body.

Expectations

Area	Detail
After mail hits the shared forwarding address	Allow about one minute after forwarding.
Connection test (UI)	May take up to ~5 minutes before timeout.
Large volumes	Large volumes may take multiple cycles to process.
Session auto-resolution	Email conversations with no activity auto-resolve after a configurable window. Contact support to adjust your org’s threshold.

Impact Of Misconfiguration

Misconfigured rules can send the wrong mail into OpenCX for an address you registered — prefer dedicated support addresses. DNS and mailbox ownership remain your responsibility.

---

Related Documentation

Connect Email

Re-check domain, provider setup, and connection test.

Email Flow

Re-check session matching, threading, and outbound format.

Autopilot And Topics

Verify channel-level Autopilot and topic rules.

Human Handoff

AI to human escalation — applies to email sessions.

Recipient changes and failed replies

• The primary contact changed, but the email failed: the transfer remains saved. Use Retry email on the failed message. Do not create another copy while its delivery is uncertain.
• Retry is unavailable after redaction: saved emails may quote earlier session content, so redaction disables existing retries in affected sessions. Review the remaining history and compose a new reply if needed. An email already delivered to a recipient cannot be recalled by redacting it in OpenCX.
• The composer says the primary contact changed: another agent updated the session after your draft began. Review To and Cc, then use the reviewed recipients before sending a new reply.
• The previous contact is not receiving updates: changing To does not put them in Cc automatically. Add them explicitly if they should receive the next email.
• An earlier participant replied, but AI did not respond: their reply can appear in the same session, but automated responses are driven by the current primary contact.
• To cannot be edited: this feature requires a connected native OpenCX email inbox and session-write permission. It does not apply to integration-backed sessions or campaign mailboxes.