> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://platform.open.cx), and a **recent message or ticket ID** if available.

<Tip>
  Looking for setup steps? See [Connect Email](/email/forwarding). For routing logic and session matching, see [Email Flow](/email/forwarding-rules).
</Tip>

## Common Troubleshooting Scenarios

| Symptom                                             | Likely cause                                                                     | What to do                                                                                                                                                                     |
| --------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Pending a long time**                             | Rule not delivering to `forwarding@opencopilot.so`, 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**](https://platform.open.cx/settings/autopilot) — 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. |

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

### AI Not Replying — Checklist

Work through in order. Stop at the first match.

1. **Autopilot disabled** — Enable it for email under [Autopilot settings](https://platform.open.cx/settings/autopilot).
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](https://platform.open.cx/settings/autopilot).
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.

<CardGroup cols={2}>
  <Card title="New emails" icon="envelope-circle-check">
    The **To** field must contain the support address you registered in the dashboard (e.g. `support@yourcompany.com`).
  </Card>

  <Card title="Replies to existing threads" icon="reply">
    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.
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Connect Email" icon="paper-plane" href="/email/forwarding">
    Re-check domain, provider setup, and connection test.
  </Card>

  <Card title="Email Flow" icon="diagram-project" href="/email/forwarding-rules">
    Re-check session matching, threading, and outbound format.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Verify channel-level Autopilot and topic rules.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI to human escalation — applies to email sessions.
  </Card>
</CardGroup>