From cf88ff4ab0837130a936b0dc445338df21b1a1b3 Mon Sep 17 00:00:00 2001 From: Pranav Date: Tue, 18 Nov 2025 16:40:14 -0800 Subject: [PATCH 1/2] chore: Update guides on email channels in self-hosted Chatwoot --- docs.json | 10 +- .../email-channel/amazon-ses-ingress.mdx | 2 +- .../email-channel/azure-app-setup.mdx | 2 +- ...conversation-continuity-using-sendgrid.mdx | 4 +- .../email-channel/conversation-continuity.mdx | 131 +++------- .../forwarding-emails-to-chatwoot.mdx | 109 ++++++++ .../email-channel/ingress-providers.mdx | 240 ++++++++++++++++++ .../features/email-channel/introduction.mdx | 35 +++ .../features/email-channel/setup.mdx | 38 --- 9 files changed, 424 insertions(+), 147 deletions(-) create mode 100644 self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx create mode 100644 self-hosted/configuration/features/email-channel/ingress-providers.mdx create mode 100644 self-hosted/configuration/features/email-channel/introduction.mdx delete mode 100644 self-hosted/configuration/features/email-channel/setup.mdx diff --git a/docs.json b/docs.json index c58a52d2..49d7fd56 100644 --- a/docs.json +++ b/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" ] }, { diff --git a/self-hosted/configuration/features/email-channel/amazon-ses-ingress.mdx b/self-hosted/configuration/features/email-channel/amazon-ses-ingress.mdx index 9b18aea0..b74479e3 100644 --- a/self-hosted/configuration/features/email-channel/amazon-ses-ingress.mdx +++ b/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. diff --git a/self-hosted/configuration/features/email-channel/azure-app-setup.mdx b/self-hosted/configuration/features/email-channel/azure-app-setup.mdx index a021c9e0..ac54d90c 100644 --- a/self-hosted/configuration/features/email-channel/azure-app-setup.mdx +++ b/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). \ No newline at end of file +Read the publishing guidelines [here](https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant). diff --git a/self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid.mdx b/self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid.mdx index 809a521e..74f74c74 100644 --- a/self-hosted/configuration/features/email-channel/conversation-continuity-using-sendgrid.mdx +++ b/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). \ No newline at end of file +You're done! Next, you should [enable the email channel](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/setup). diff --git a/self-hosted/configuration/features/email-channel/conversation-continuity.mdx b/self-hosted/configuration/features/email-channel/conversation-continuity.mdx index af99397e..4c4df2ae 100644 --- a/self-hosted/configuration/features/email-channel/conversation-continuity.mdx +++ b/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 - - -Conversation Continuity requires your chatwoot installation to have a [cloud storage configured](/self-hosted/deployment/storage/supported-providers) - +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= -``` + After finishing the set up, the mail sent from Chatwoot will have a `replyto:` in the following format `reply+@` and reply to those would get appended to your conversation. diff --git a/self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx b/self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx new file mode 100644 index 00000000..5eebfc10 --- /dev/null +++ b/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. + + + +Forwarding emails to Chatwoot requires a [cloud storage configured](/self-hosted/deployment/storage/supported-providers) + + +## 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](./self-hosted/configuration/features/email-channel/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. diff --git a/self-hosted/configuration/features/email-channel/ingress-providers.mdx b/self-hosted/configuration/features/email-channel/ingress-providers.mdx new file mode 100644 index 00000000..c3a92d67 --- /dev/null +++ b/self-hosted/configuration/features/email-channel/ingress-providers.mdx @@ -0,0 +1,240 @@ +--- +title: Configuring inbound mails in Chatwoot +description: Guide to set up inbound emails in Chatwoot +sidebarTitle: Ingress Providers +--- + +Chatwoot uses [Rails Action Mailbox](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) to receive inbound emails. Action Mailbox supports multiple "ingress" providers out of the box, and Chatwoot builds on top of that. + +This guide walks you through: + +* Choosing and configuring an inbound email (ingress) provider +* Setting the required environment variables +* Using Mailgun, SendGrid, Mandrill, and local relay servers (Exim, Postfix, Qmail, Postmark) + +Supported ingress providers today: + +* Amazon SES +* SendGrid +* Mandrill +* Mailgun +* Exim +* Postfix +* Qmail +* Postmark + + + +## 1. Configure the ingress service + +First, tell Chatwoot which inbound email service (ingress) you are using. This is done via the `RAILS_INBOUND_EMAIL_SERVICE` environment variable. + +```bash +# Set this to the appropriate ingress service. Options: +# "relay" for Exim, Postfix, Qmail, Postmark +# "mailgun" for Mailgun +# "mandrill" for Mandrill +# "sendgrid" for SendGrid +# "ses" for Amazon SES +RAILS_INBOUND_EMAIL_SERVICE=relay +``` + +This value configures how Action Mailbox will authenticate and route inbound messages into Chatwoot. + +### Using a local relay (Postfix / Exim / Qmail / Postmark) + +If you are using a local MTA (for example Postfix) for both inbound relaying and outbound email, and you **do not** want to use SMTP authentication (SASL) — which is common when the server only handles its own mail — you need to adjust your outbound SMTP configuration. + +By default, Action Mailer will try to use SMTP authentication if the following environment variables are present: + +* `SMTP_AUTHENTICATION` +* `SMTP_USERNAME` +* `SMTP_PASSWORD` + +If you are sending mail through a local relay that does not require authentication: + +1. Remove or comment out these variables from your `.env` file. +2. Ensure that your local MTA is correctly configured to send outbound mail. + +> ⚠️ **Important:** Running your own mail server comes with deliverability and security responsibilities: +> +> * Many ISPs block or restrict email servers on their networks. +> * Configure proper DNS records (SPF, DKIM, DMARC) so that your emails are accepted by recipients and do not land in spam. + + +## 2. Configure ingress authentication + +Next, set the corresponding credentials for the ingress provider you’re using. + +```bash +# Use one of the following based on the email ingress service + +# For SendGrid, Exim, Postfix, Qmail, or Postmark +RAILS_INBOUND_EMAIL_PASSWORD= + +# For Mailgun +MAILGUN_INGRESS_SIGNING_KEY= + +# For Mandrill +MANDRILL_INGRESS_API_KEY= +``` + +Only the relevant variable for your chosen provider needs to be configured. + + +## 3. Provider-specific configuration + +### Amazon SES + +If you are using Amazon SES as your email provider, you have configure the ingress provider as `ses` and set the `ACTION_MAILBOX_SES_SNS_TOPIC` to the SNS topic ARN of your SES account. + +See more details [here](./amazon-ses-ingress). + +### Mailgun + +If you are using Mailgun as your email provider: + +1. In your DNS, configure the **MX records** for your domain to point to Mailgun. +2. In the Mailgun dashboard, configure routing so that inbound emails are forwarded to: + +```text +https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime +``` + +Replace `example.com` with the domain where your Chatwoot installation is hosted. + +#### Getting the Mailgun ingress signing key + +You can find the signing key in your Mailgun dashboard and set it as `MAILGUN_INGRESS_SIGNING_KEY`. + +![mailgun-ingress-key](/self-hosted/images/mailgun-ingress-key.gif) + + + +### SendGrid + +If you are using SendGrid: + +1. Configure **MX records** for your domain (`your-domain.com`) to point to SendGrid. +2. In the SendGrid dashboard, set up **Inbound Parse** to forward inbound emails to the Action Mailbox endpoint. + +Use the following pattern as the Inbound Parse URL: + +```bash +https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails +``` + +* Replace `PASSWORD` with the value of `RAILS_INBOUND_EMAIL_PASSWORD`. +* Replace `example.com` with your Chatwoot host. + +> ✅ **Required:** When configuring the SendGrid Inbound Parse webhook, **enable** the option: +> +> **"Post the raw, full MIME message"**. +> +> Action Mailbox must receive the raw MIME message to correctly parse and process the email. + +See a detailed guide on [how to configure SendGrid Inbound Parse](./conversation-continuity-using-sendgrid). + + + +### Mandrill + +If you are using Mandrill as your email service: + +1. Configure your domain’s MX records to point to Mandrill. +2. In the Mandrill dashboard, configure an inbound route that forwards emails to: + +```text +https://example.com/rails/action_mailbox/mandrill/inbound_emails +``` + +Replace `example.com` with the domain where your Chatwoot installation is hosted. + +Set `MANDRILL_INGRESS_API_KEY` with the appropriate API key from Mandrill. + + + +## 4. IMAP via getmail + +If you already have an IMAP mailbox (for example on your own mail server or with a provider that doesn’t directly support Action Mailbox), you can still feed emails into Chatwoot using [getmail6](https://github.com/getmail6/getmail6) and the Action Mailbox HTTP ingress. + +### How Action Mailbox ingress works + +Action Mailbox exposes HTTP endpoints for each ingress type. They are defined in the Rails source and can also be used directly. + +Example using the Rails rake task: + +```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=... +``` + +This imports the contents of `my_incoming_message` (an [RFC 822](https://datatracker.ietf.org/doc/html/rfc822) compliant message) into a Chatwoot instance running on `localhost`. + +### Calling the HTTP endpoint directly + +Instead of using the Rake task, you can call the ingress HTTP endpoint directly via `curl`. + +```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 +``` + +This sends the raw message from stdin to the Action Mailbox relay endpoint. + +### Using getmail6 with IMAP + +[getmail6](https://github.com/getmail6/getmail6) can retrieve emails from an IMAP mailbox and pipe them into the `curl` script above. + +If the script is stored at `/home/chatwoot/bin/import_mail_to_chatwoot`, a minimal `getmail` configuration might look like this: + +```ini +[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 +``` + +### Scheduling mail retrieval + +To continuously import mail into Chatwoot, you need to run `getmail` regularly. Common options: + +* Use `cron` to run `getmail` at a fixed interval (for example every minute). +* For IMAP, you can use: + +```bash +getmail --idle INBOX +``` + +This keeps a long-lived connection open and reacts to new mail immediately. You’ll need some supervision (systemd, runit, etc.) to handle restarts if the connection is interrupted. + + + +## 5. Further reading + +For more details on configuring and customizing ingresses, refer to the official Rails documentation: + +* [Action Mailbox Basics – Configuration](https://edgeguides.rubyonrails.org/action_mailbox_basics.html#configuration) diff --git a/self-hosted/configuration/features/email-channel/introduction.mdx b/self-hosted/configuration/features/email-channel/introduction.mdx new file mode 100644 index 00000000..65fbc464 --- /dev/null +++ b/self-hosted/configuration/features/email-channel/introduction.mdx @@ -0,0 +1,35 @@ +--- +title: Introduction to Email Channel Configuration +description: Overview of email channel configuration for self-hosted Chatwoot +sidebarTitle: Introduction +--- + +Email is one of the core channels in Chatwoot, and for self-hosted installations the configuration depends entirely on how your mail infrastructure is set up. Different teams use different providers—Google Workspace, Microsoft 365, custom SMTP/IMAP servers, or even forwarding-based workflows. Because of this, Chatwoot provides multiple ways to connect a mailbox, each with slightly different requirements, security properties, and operational trade-offs. + +This guide introduces the five supported configurations available in Chatwoot for setting up email channels in a self-hosted environment. All of these methods allow Chatwoot to send and receive email, but the authentication flow, inbound routing, and outbound delivery differ based on your setup. + +### Google (OAuth based) + +If you are using Gmail or Google Workspace, you can connect your mailbox using Google OAuth. This provides a secure, standards-based authentication flow without managing app passwords. Chatwoot will use Google's SMTP and IMAP servers for sending and receiving. + +Click here to learn more about [Google Workspace Setup](./google-workspace-setup). + +### Microsoft (OAuth based) + +For organizations using Microsoft 365 or Outlook, you can connect your mailbox using Microsoft OAuth. Chatwoot integrates with Microsoft’s SMTP and IMAP endpoints for full send/receive capability. + +Click here to learn more about [Microsoft Setup](./azure-app-setup). + +### Standard SMTP + IMAP + +This configuration supports any custom mail provider by allowing you to set standard SMTP credentials for outbound mail and IMAP credentials for inbound. This works with on‑prem servers, commercial providers, or any setup that supports username/password authentication. + +### Forwarding Rule (Email → Chatwoot Ingress) + +Instead of configuring IMAP, some teams prefer to forward incoming emails directly to Chatwoot. If your mail provider supports forwarding rules, you can send inbound email to Chatwoot’s ingress address, which Chatwoot will process as incoming messages. Outbound email will use your configured SMTP provider. + +### IMAP (Inbound Only) + Chatwoot Mailer (Outbound) + +In this mode, Chatwoot pulls inbound email through IMAP but sends outbound messages using Chatwoot’s mailer configuration. This is useful when your mail provider imposes SMTP restrictions or when you want a consistent outbound delivery method across channels. + +You just need to configure IMAP settings here. diff --git a/self-hosted/configuration/features/email-channel/setup.mdx b/self-hosted/configuration/features/email-channel/setup.mdx deleted file mode 100644 index 1f6634e8..00000000 --- a/self-hosted/configuration/features/email-channel/setup.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Email Channel Setup -description: Setting up Email Channel in Chatwoot -sidebarTitle: Email Channel Setup ---- - -## Configure Email Channel - - -Email channels require [conversation continuity configured](/self-hosted/configuration/features/email-channel/conversation-continuity) - - -1. Enable `channel_email` (Login to rails console and execute the following) - -```bash -account = Account.find(1) -account.enabled_features // This would list enabled features. -account.enable_features('channel_email') -account.save! -``` - -2. Now head over to inboxes page and create an email inbox with the support email as care@your-domain.com -![mail-channel-step1](/self-hosted/images/mail-channel-step1.png) -3. Now Add Agents who can have access to the email channel box. -4. Now you will get the email channel box address in the last step. -![mail-channel-step2](/self-hosted/images/mail-channel-step2.png) -5. Now create a forward rule in your care@your-domain.com inbox to forward emails to the address obtained at inbox creation step. -![set-forwarder-email](/self-hosted/images/set-forwarder-email.png) -6. You should be able to receive emails in your newly created email inbox in chatwoot. -![mail-channel-box](/self-hosted/images/mail-channel-box.png) - -### Sendgrid - -You can send out emails only from a verified email address in SendGrid. For sending emails from wildcard domain, do verification at domain level instead of individual email. - -### Testing On Local - -You can visit `http://localhost:3000/rails/conductor/action_mailbox/inbound_emails/new` to send inbound mails from local to chatwoot inbox. From 419ad57d15c872bf20e3163adf0137bbe4015d51 Mon Sep 17 00:00:00 2001 From: Pranav Date: Tue, 18 Nov 2025 16:43:00 -0800 Subject: [PATCH 2/2] fix broken link --- .../features/email-channel/forwarding-emails-to-chatwoot.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx b/self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx index 5eebfc10..26c27e9a 100644 --- a/self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx +++ b/self-hosted/configuration/features/email-channel/forwarding-emails-to-chatwoot.mdx @@ -77,7 +77,7 @@ The setup varies slightly across providers, but the steps are generally: 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](./self-hosted/configuration/features/email-channel/ingress-providers). +See more details [here](./ingress-providers). ## Outbound Email Behavior