chore: Update guides on email channel configuration in self-hosted Chatwoot

docs.json

@@ -115,12 +115,14 @@
               {
                 "group": "Email Channel",
                 "pages": [
+                  "self-hosted/configuration/features/email-channel/introduction",
+                  "self-hosted/configuration/features/email-channel/google-workspace-setup",
+                  "self-hosted/configuration/features/email-channel/azure-app-setup",
+                  "self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot",
+                  "self-hosted/configuration/features/email-channel/ingress-providers",
                   "self-hosted/configuration/features/email-channel/conversation-continuity",
                   "self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid",
-                  "self-hosted/configuration/features/email-channel/amazon-ses-ingress",
-                  "self-hosted/configuration/features/email-channel/setup",
-                  "self-hosted/configuration/features/email-channel/azure-app-setup",
-                  "self-hosted/configuration/features/email-channel/google-workspace-setup"
+                  "self-hosted/configuration/features/email-channel/amazon-ses-ingress"
                 ]
               },
               {

self-hosted/configuration/features/email-channel/amazon-ses-ingress.mdx

@@ -1,7 +1,7 @@
 ---
 title: Configuring Amazon SES as an Ingress Provider for Chatwoot
 description: Guide to setting up conversation continuity, inbound emails with Amazon SES
-sidebarTitle: SES Ingress
+sidebarTitle: Amazon SES Ingress
 ---
 
 This guide explains how to set up Amazon SES as the incoming email (ingress) provider for your self-hosted Chatwoot installation. If you plan to use Chatwoot’s email forwarding option and want SES to handle inbound mail delivery into Chatwoot, this documentation is for you.

self-hosted/configuration/features/email-channel/azure-app-setup.mdx

@@ -90,4 +90,4 @@ To test the changes before the app is verified for production, use the Entra ID
 
 Publisher verification provides app users and organization admins with information about the authenticity of the developer's organization that publishes an app integrating with the Microsoft identity platform. If an app has a verified publisher, it means that Microsoft has verified the authenticity of the organization that publishes the app.
 
-Read the publishing guidelines [here](https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant). 
+Read the publishing guidelines [here](https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant).

self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid.mdx

@@ -1,7 +1,7 @@
 ---
 title: SendGrid Guide
 description: Guide to setting up Conversation Continuity with SendGrid
-sidebarTitle: SendGrid Guide
+sidebarTitle: SendGrid Ingress
 ---
 
 This doc will help you set up [Conversation continuity](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/conversation-continuity) with SendGrid.
@@ -80,4 +80,4 @@ You should change ``support.example.com`` to the domain you used with SendGrid.
 
 ## Next steps
 
-You're done! Next, you should [enable the email channel](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/setup). 
+You're done! Next, you should [enable the email channel](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/setup).

self-hosted/configuration/features/email-channel/conversation-continuity.mdx

@@ -1,124 +1,53 @@
 ---
 title: Conversation Continuity
-description: Configure Conversation Continuity with Email
+description: Continue conversations between website live chat and email
 sidebarTitle: Conversation Continuity
 ---
 
-## Conversation continuity
+When a customer starts a conversation on your website, you don’t want the thread to break just because the user went offline. Chatwoot automatically maintains continuity between the website live chat and email, so the conversation stays in one place for both your agents and your customers.
 
-![101382999-9b0abf00-38de-11eb-845d-1bb1f52306df@2x](https://user-images.githubusercontent.com/73185/109548415-a1ca5c00-7af2-11eb-9b1d-fd636cf5189c.png)
-
-## Configuring inbound reply emails
-
-<Note>
-Conversation Continuity requires your chatwoot installation to have a [cloud storage configured](/self-hosted/deployment/storage/supported-providers)
-</Note>
+This guide explains how that flow works and what you should set up to ensure everything stays seamless.
 
-There are a couple of email infrastructure service providers to handle the incoming emails that we support at the moment. They are
-Sendgrid, Mandrill, Mailgun, Exim, Postfix, Qmail and Postmark.
+### How Conversation Continuity Works
 
-Step 1 : We have to set the inbound email service used as an environment variable.
+#### 1. Customer starts a conversation
 
-```bash
-# Set this to appropriate ingress service for which the options are :
-# "relay" for Exim, Postfix, Qmail
-# "mailgun" for Mailgun
-# "mandrill" for Mandrill
-# "postmark" for Postmark
-# "sendgrid" for Sendgrid
-RAILS_INBOUND_EMAIL_SERVICE=relay
-```
-If you wish to use the same local relaying server (for example postfix) to send outbound mail as you are using to relay inbound messages and you opt not to use an external authentication mechanism like SASL which may be the case if the server is handling it own emails only. The upstream SMTP platform Action Mailer attempts to use a default authentication method if the configuration options `SMTP_AUTHENTICATION`, `SMTP_USERNAME` and `SMTP_PASSWORD` are present in your .env file. To disable this behaviour either comment out or delete these lines from your configuration. This will allow you to send outbound messages from the same server without a premium service. Please note many ISP's do not allow email servers to be run from their networks. It is your responsibility to ensure adequate access control preventing yourself becoming an open relay and ensuring your server is able to get past your recipients spam filters for example SPF, DKIM & DMARC dns records.
+The customer interacts with your widget and starts a conversation.
+If Email Collect is enabled, the widget asks the customer for their email address.
+This email becomes the identifier for all future messages.
 
-This configures the ingress service for the app. Now we have to set the password for the ingress service that we use.
+#### 2. Customer goes offline, agent replies
 
-```bash
-# Use one of the following based on the email ingress service
+If the agent replies when the customer is no longer online, Chatwoot delivers the agent’s reply to the customer via email.
+This ensures the user doesn’t miss the update.
 
-# Set this if you are using Sendgrid, Exim, Postfix, Qmail or Postmark
-RAILS_INBOUND_EMAIL_PASSWORD=
-# Set this if you are Mailgun
-MAILGUN_INGRESS_SIGNING_KEY=
-# Set this if you are Mandrill
-MANDRILL_INGRESS_API_KEY=
-```
+#### 3. Customer replies from their email
 
-### Mailgun
-If you are using Mailgun as your email service, in the Mailgun dashboard configure it to forward your inbound emails to `https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime` if `example.com` is where you have hosted the application.
+The user sees your message in their inbox and simply replies to that email like any normal thread.
+They don’t need to come back to your website manually — replying from email is enough.
 
-#### Getting Mailgun Ingress Key
-![mailgun-ingress-key](/self-hosted/images/mailgun-ingress-key.gif)
+#### 4. Chatwoot processes the email and links it to the conversation
 
-### Sendgrid
+When Chatwoot receives the user’s email:
+	•	It reads the email headers (Message-ID / References / custom thread identifiers)
+	•	It maps the email to the correct conversation thread
+	•	It adds the user’s reply as a new message inside the same live-chat conversation
 
-Ensure to set up the proper MX records for `your-domain.com` pointed towards Sendgrid
+To the agent, it looks like the user never left.
+To the user, it feels like replying to any normal email thread.
 
-Configure SendGrid Inbound Parse to forward inbound emails to forward your inbound emails to `/rails/action_mailbox/sendgrid/inbound_emails` with the username `actionmailbox` and the password you previously generated. If the deployed application was hosted at `example.com`, you can configure the following URL as the forward route.
+### What You Need to Enable
 
-```bash
-https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
-```
+#### 1. Email Collect Hook
+Make sure the widget is configured to collect the user’s email early in the conversation.
+This is the key to linking email replies back to the same thread.
 
-When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled "Post the raw, full MIME message." Action Mailbox needs the raw MIME message to work.
+#### 2. Email channel configuration
+Make sure email forwarding is enabled as per this guide: [Forwarding Emails to Chatwoot](./forwarding-emails-to-chatwoot).
 
-### Mandrill
-If you are configuring Mandrill as your email service, configure Mandrill to route your inbound emails to `https://example.com/rails/action_mailbox/mandrill/inbound_emails` if `example.com` is where you have hosted the application.
+#### 3. Mailer configuration
+Outbound emails should be properly configured so Chatwoot can notify the customer when the agent replies offline.
 
-If you want to know more about configuring other services visit [Action Mailbox Basics](https://edgeguides.rubyonrails.org/action_mailbox_basics.html#configuration)
-
-### IMAP via getmail
-Chatwoot receives inbound emails through the [Action Mailbox](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) feature of Ruby on Rails. Action Mailbox supports various 'ingresses' by default. They are defined in [here](https://github.com/rails/rails/blob/main/actionmailbox/lib/tasks/ingress.rake) and can be executed through `bin/rails`. For example
-```bash
-cat my_incoming_message | ./bin/rails action_mailbox:ingress:postfix \
-  RAILS_ENV=production \
-  URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails \
-  INGRESS_PASSWORD=...
-```
-would import the contents of the file `my_incoming_message` into a Chatwoot instance running on `localhost` - assuming `my_incoming_message` contains an [RFC 822](https://datatracker.ietf.org/doc/html/rfc822) compliant message.
-
-The ingress tasks provided by Action Mailbox are a thin layer around an HTTP endpoint exposed by Action Mailbox. An alternative to using those tasks is to talk to the http endpoint directly. The following script achieves the same.
-```bash
-INGRESS_PASSWORD=...
-URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails
-
-curl -sS -u "actionmailbox:$INGRESS_PASSWORD" \
- -A "Action Mailbox curl relayer" \
- -H "Content-Type: message/rfc822" \
- --data-binary @- \
- $URL
-```
-
-The popular mail retrieval system [getmail6](https://github.com/getmail6/getmail6) can be used to fetch mails and import them into Chatwoot. If the curl script above is stored in `/home/chatwoot/bin/import_mail_to_chatwoot`, a configuration for doing so from an IMAP inbox is as follows.
-```
-[retriever]
-type = SimpleIMAPSSLRetriever
-server = ...
-username = ...
-password = ...
-
-[destination]
-type = MDA_external
-path = /home/chatwoot/bin/import_mail_to_chatwoot
-
-[options]
-verbose = 0
-read_all = false
-delete = false
-delivered_to = false
-received = false
-message_log = /home/chatwoot/logs/import_imap.log
-message_log_syslog = false
-message_log_verbose = true
-```
-
-For mail to be imported you'll need to execute `getmail` regularly, for example using a cron job. For `IMAP` you can also run it constantly using `getmail --idle INBOX`, though that will need some care to deal with interrupted connections, etc.
-
-## Configure inbound email domain environment variable
-
-Add the following environment variable with the value `your-domain.com`, where `your-domain.com` is the domain for which you set up MX records in the previous step.
-
-```bash
-MAILER_INBOUND_EMAIL_DOMAIN=
-```
+<img src="https://user-images.githubusercontent.com/73185/109548415-a1ca5c00-7af2-11eb-9b1d-fd636cf5189c.png" height="300px" />
 
 After finishing the set up, the mail sent from Chatwoot will have a `replyto:` in the following format `reply+<random-hex>@<your-domain.com>` and reply to those would get appended to your conversation.

self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx

@@ -0,0 +1,109 @@
+---
+title: Forwarding Emails to Chatwoot
+description: Guide to set up email forwarding to Chatwoot
+sidebarTitle: Forwarding
+---
+
+This guide explains how to set up email forwarding to Chatwoot when you prefer not to configure IMAP. Forwarding allows your email provider to push inbound messages directly to Chatwoot, which then processes them as incoming conversations in your inbox.
+
+
+<Note>
+Forwarding emails to Chatwoot requires a [cloud storage configured](/self-hosted/deployment/storage/supported-providers)
+</Note>
+
+## When to Use Forwarding
+
+Forwarding is a good option if:
+
+* You don’t want to use IMAP or your provider does not allow IMAP access.
+* You want a simple, push‑based way to deliver inbound emails to Chatwoot.
+* Your provider supports routing or forwarding rules (Gmail, Google Workspace, Outlook, Fastmail, Zoho, custom servers, etc.).
+* You already use SMTP for outbound mail and just need a lightweight inbound setup.
+
+## How Forwarding Works in Chatwoot
+
+Each email inbox in Chatwoot is assigned an ingress address—a unique, system‑generated email address. When your provider forwards an email to that address, Chatwoot. Note: For installations using an ingress provider (SES, SendGrid, Mailgun, etc.), you must configure an MX record pointing to the ingress provider so that inbound email is accepted and routed correctly.
+
+
+1. Ingress provider receives the email and forwards it to the configured Chatwoot URL.
+2. Chatwoot parses the content, attachments, headers, and thread references.
+3. Creates or updates the conversation in the appropriate inbox.
+4. Handles message threading properly via `Message-ID`, `References`, and `In-Reply-To`.
+
+Outbound email continues to use your configured SMTP provider.
+
+
+## Requirements
+
+To use forwarding successfully, ensure:
+
+* **Email ingress is enabled on your Chatwoot installation.** Some self-hosted setups disable ingress by default for security.
+* **Your installation supports inbound processing** via the configured mailer/ingress pipeline.
+* **The forwarding rule is set to forward *all* relevant mail**, including replies.
+* **SPF, DKIM, and DMARC** are correctly configured on your domain for good deliverability.
+
+If ingress is disabled, Chatwoot will show a warning in the UI. Your administrator must enable it before forwarding works.
+
+The receiving domain should be configured in the environment variable `MAILER_INBOUND_EMAIL_DOMAIN`.
+
+```
+MAILER_INBOUND_EMAIL_DOMAIN=
+```
+
+
+## Finding the Forwarding Address
+
+In Chatwoot:
+
+1. Go to your inbox settings.
+2. Select your email channel settings -> Configuration
+3. Copy the provided **Chatwoot ingress email address**.
+
+This address is unique per inbox.
+
+
+
+## Configuring Forwarding on Your Email Provider
+
+The setup varies slightly across providers, but the steps are generally:
+
+1. Open your email provider's forwarding or routing settings.
+2. Add the Chatwoot ingress email as a forwarding destination.
+3. Verify the address if the provider requires confirmation.
+4. Set a rule to forward all incoming email (or only relevant messages) to the ingress address.
+5. Save the configuration.
+
+## Configuring Ingress Provider
+
+For Chatwoot installations, a dedicated ingress provider (Amazon SES, SendGrid, Mailgun, etc.) is required. The provider acts as the first receiver of your domain’s email and then forwards it to the Chatwoot ingress URL.
+
+See more details [here](./ingress-providers).
+
+## Outbound Email Behavior
+
+Forwarding affects **only inbound** messages.
+Outbound messages will still be sent using:
+
+* The SMTP provider you configured for the inbox (recommended), or
+* The default SMTP provider configured in the Chatwoot installation.
+
+
+## Troubleshooting
+
+Common issues:
+
+### 1. Forwarding Not Enabled in Chatwoot
+
+If you see: *“Support for forwarding emails is not configured. Contact your administrator.”*
+Your Chatwoot installation must enable email ingress. MAILER_INBOUND_EMAIL_DOMAIN configuration is missing.
+
+### 2. Emails Not Appearing in the Inbox
+
+Check:
+* Forwarding rule is enabled and active.
+* Provider is not suppressing or classifying forwarded mail.
+* No DMARC quarantine/reject issues.
+* The ingress address is correct.
+
+### 3. Threading Issues
+Chatwoot relies on message headers for threading. Ensure your provider forwards headers intact.