Client configuration guides

docs/client-android.md

@@ -0,0 +1,5 @@
+1. Open the *Email* app.
+2. If this is your first email account, tap *Add Account*; if not, tap *More* and *Settings* and then *Add account*.
+3. Select *Microsoft Exchange ActiveSync*.
+4. Enter your email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and password.
+5. Tap *Sign in*.

docs/client-apple.md

@@ -0,0 +1,10 @@
+1. Download and open <a class="client_var_link" href="mobileconfig.php">Mailcow.mobileconfig</a>.
+2. Enter the unlock code (iPhone) or computer password (Mac).
+3. Enter your email password three times when prompted.
+
+On iOS, Exchange is also supported as an alternative to the procedure above. It has the advantage of supporting push email (i.e. you are immediately notified of incoming messages), but has some limitations, e.g. it does not support more than three email addresses per contact in your address book. Follow the steps below if you decide to use Exchange instead.
+
+1. Open the *Settings* app, tap *Mail*, tap *Accounts*, tap *Add Acccount*, select *Exchange*.
+2. Enter your email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and tap *Next*.
+3. Enter your password, tap *Next* again.
+4. Finally, tap *Save*.

docs/client-emclient.md

@@ -0,0 +1,7 @@
+1. Launch eM Client.
+2. If this is the first time you launched eM Client, it asks you to set up your account. Proceed to step 4.
+3. Go to *Menu* at the top, select *Tools* and *Accounts*.
+4. Enter your email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and click *Start Now*.
+5. Enter your password and click *Continue*.
+6. Enter your name<span class="client_variables_available"> (<code><span class="client_var_name"></span></code>)</span> and click *Next*.
+7. Click *Finish*.

docs/client-kontact.md

@@ -0,0 +1,16 @@
+1. Launch Kontact.
+2. If this is the first time you launched Kontact or KMail, it asks you to set up your account. Proceed to step 4.
+3. Go to *Mail* in the sidebar. Go to the *Tools* menu and select *Account Wizard*.
+4. Enter your name<span class="client_variables_available"> (<code><span class="client_var_name"></span></code>)</span>, email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and your password. Click *Next*.
+5. Click *Create Account*. If prompted, re-enter your password and click *OK*.
+6. Close the window by clicking *Finish*.
+7. Go to *Calendar* in the sidebar.
+8. Go to the *Settings* menu and select *Configure KOrganizer*.
+9. Go to the *Calendars* tab and click the *Add* button.
+10. Choose *DAV groupware resource* and click *OK*.
+11. Enter your email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and your password. Click *Next*.
+12. Select *ScalableOGo* from the dropdown menu and click *Next*.
+13. Enter<span class="client_variables_available"> <code><span class="client_var_host"></span><span class="client_var_port"></span></code></span><span class="client_variables_unavailable"> your Mailcow hostname</span> into the *Host* field and click *Next*.
+14. Click *Test Connection* and then *Finish*. Finally, click *OK* twice.
+
+Once you have set up Kontact, you can also use KMail, KOrganizer and KAddressBook individually.

docs/client-outlook.md

@@ -0,0 +1,42 @@
+<div class="client_outlookEAS_enabled" markdown="1">
+
+## Outlook 2013 or higher on Windows
+
+<div class="client_variables_unavailable" markdown="1">
+  This is only applicable if your server administrator has not disabled EAS for Outlook. If it is disabled, please follow the guide for Outlook 2007 instead.
+</div>
+
+1. Launch Outlook.
+2. If this is the first time you launched Outlook, it asks you to set up your account. Proceed to step 4.
+3. Go to the *File* menu and click *Add Account*.
+4. Enter your name<span class="client_variables_available"> (<code><span class="client_var_name"></span></code>)</span>, email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and your password. Click *Next*.
+5. When prompted, enter your password again, check *Remember my credentials* and click *OK*.
+6. Click the *Allow* button.
+7. Click *Finish*.
+
+## Outlook 2007 or 2010 on Windows
+
+</div>
+
+<div class="client_outlookEAS_disabled" markdown="1">
+
+## Outlook 2007 or higher on Windows
+
+</div>
+
+1. Download and install [Outlook CalDav Synchronizer](https://caldavsynchronizer.org).
+2. Launch Outlook.
+3. If this is the first time you launched Outlook, it asks you to set up your account. Proceed to step 5.
+4. Go to the *File* menu and click *Add Account*.
+5. Enter your name<span class="client_variables_available"> (<code><span class="client_var_name"></span></code>)</span>, email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and your password. Click *Next*.
+6. Click *Finish*.
+7. Go to the *CalDav Synchronizer* ribbon and click *Synchronization Profiles*.
+8. Click the second button at top (*Add multiple profiles*), select *Sogo*, click *Ok*.
+9. Click the *Get IMAP/POP3 account settings* button.
+10. Click *Discover resources and assign to Outlook folders*.
+11. In the *Select Resource* window that pops up, select your main calendar (usually *Personal Calendar*), click the *...* button, assign it to *Calendar*, and click *OK*. Go to the *Address Books* and *Tasks* tabs and repeat repeat the process accordingly. Do not assign multiple calendars, address books or task lists!
+12. Close all windows with the *OK* buttons.
+
+## Outlook 2011 or higher on macOS
+
+The Mac version of Outlook does not synchronize calendars and contacts and therefore is not supported.

docs/client-thunderbird.md

@@ -0,0 +1,53 @@
+<ol>
+<li>
+  Launch Thunderbird.
+</li>
+<li>
+  If this is the first time you launched Thunderbird, it asks you whether you would like a new email address. Click <i>Skip this and use my existing email</i> and proceed to step 4.
+</li>
+<li>
+  Go to the <i>Tools</i> menu and select <i>Account Settings</i>.
+</li>
+<li>
+  Click the <i>Account Actions</i> dropdown menu at the bottom left and select <i>Add Mail Account</i>.
+</li>
+<li>
+  Enter your name<span class="client_variables_available"> (<code><span class="client_var_name"></span></code>)</span>, email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and your password. Make sure the <i>Remember password</i> checkbox is selected and click <i>Continue</i>.
+</li>
+<li>
+  Once the configuration has been automatically detected, click <i>Done</i>.
+</li>
+<li>
+  If you already had other accounts configured in Thunderbird, select the new one<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> on the left, click the <i>Account Actions</i> dropdown and select Set as <i>Default</i>.
+</li>
+<li>
+  Close the account settings window with the <i>OK</i> button.
+</li>
+<li class="client_integrator_enabled">
+  In your web browser, download <a class="client_var_integrator_link" href="/thunderbird-plugins/sogo-integrator-__VERSION__-__DOMAIN__.xpi">SOGo Integrator</a>.
+</li>
+<li class="client_integrator_enabled">
+  Back in Thunderbird, go to the <i>Tools</i> menu and select <i>Add-ons</i>.
+</li>
+<li class="client_integrator_enabled">
+  Click <i>Extensions</i> on the left, click the little gear icon at the top and select <i>Install Add-on From File</i>. Select the file you downloaded in step 9, click <i>Open</i> and, after waiting for a few seconds, <i>Install Now</i>.
+</li>
+<li class="client_integrator_enabled">
+  Click the <i>Restart Now</i> button at the top that appears.
+</li>
+<li class="client_integrator_enabled">
+  Thunderbird briefly shows a message that it is updating extensions, then restarts automatically once more.
+</li>
+<li class="client_integrator_enabled">
+  When you are prompted to authenticate<span class="client_variables_available"> for <code><span class="client_var_host"></span><span class="client_var_port"></span></code></span>, enter your email address and password, check <i>Use Password Manager</i> and click <i>OK</i>.
+</li>
+</ol>
+
+<div class="client_integrator_disabled client_variables_available" markdown="1">
+Automatic configuration of calendars and address books in Thunderbird is not currently supported.
+      You can ask your server administrator to enable [SOGo Integrator](third_party-thunderbird) if you need it.
+</div>
+
+<div class="client_variables_unavailable" markdown="1">
+Automatic configuration of calendars and address books (from step 9 onward) in Thunderbird is only supported if your server administrator has enabled [SOGo Integrator](third_party-thunderbird).
+</div>

docs/client-windows.md

@@ -0,0 +1,8 @@
+1. Open the *Mail* app.
+2. If you have not previously used Mail, you can click *Add Account* in the main window. Proceed to step 4.
+3. Click *Accounts* in the sidebar on the left, then click *Add Account* on the far right.
+4. Select *Exchange*.
+5. Enter your email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and click *Next*.
+6. Enter your password and click *Log in*.
+
+Once you have set up the Mail app, you can also use the People and Calendar apps.

docs/client-windowsphone.md

@@ -0,0 +1,4 @@
+1. Open the *Settings* app. Select *email + accounts* and tap *add an account*.
+2. Tap *Exchange*.
+3. Enter your email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and your password. Tap *Sign in*.
+4. Tap *done*.

docs/client.md

@@ -0,0 +1,11 @@
+Mailcow supports a variety of email clients, both on desktop computers and on smartphones.
+Below, you can find a number of configuration guides that explain how to configure your Mailcow account.
+
+- [Android](client-android)
+- [Apple iOS / macOS](client-apple)
+- [eM Client](client-emclient)
+- [KDE Kontact / KMail](client-kontact)
+- [Microsoft Outlook](client-outlook)
+- [Mozilla Thunderbird](client-thunderbird)
+- [Windows](client-windows)
+- [Windows Phone](client-windowsphone)

docs/clients.js

@@ -0,0 +1,112 @@
+if (window.location.href.indexOf('/client/') >= 0) {
+    window.onload = function () {
+        function getParameterByName(name) {
+            var match = RegExp('[?#&]' + name + '=([^&]*)').exec(window.location.hash);
+            return match && decodeURIComponent(match[1].replace(/\+/g, ' '));
+        }
+    
+        /* Store URL variables in cookies */
+        if (getParameterByName('host')) {
+            document.cookie = "host=" + getParameterByName('host') + "; path=/";
+        }
+        if (getParameterByName('email')) {
+            var email = getParameterByName('email');
+            document.cookie = "email=" + email + "; path=/";
+            document.cookie = "domain=" + email.substring(email.indexOf('@') + 1) + "; path=/";
+        }
+        if (getParameterByName('name')) {
+            document.cookie = "name=" + getParameterByName('name') + "; path=/";
+        }
+        if (getParameterByName('port')) {
+            document.cookie = "port=" + getParameterByName('port') + "; path=/";
+        }
+        if (getParameterByName('integrator')) {
+            document.cookie = "integrator=" + getParameterByName('integrator') + "; path=/";
+        }
+        if (getParameterByName('outlookEAS')) {
+            document.cookie = "outlookEAS=" + getParameterByName('outlookEAS') + "; path=/";
+        }
+    }
+}
+
+if (window.location.href.indexOf('/client-') >= 0) {
+    window.onload = function () {
+        function getCookie(cn) {
+            var cs = document.cookie.split(';');
+            for (var i = 0; i < cs.length; i++) {
+                var c = cs[i];
+                while (c.charAt(0) == ' ') {
+                    c = c.substring(1);
+                }
+                if (c.indexOf(cn + "=") == 0) {
+                    return c.substring(cn.length + 1, c.length);
+                }
+            }
+            return "";
+        }
+    
+        /* Hide variable fields if no values are available */
+        if (!getCookie('host')) {
+            Array.prototype.forEach.call(document.getElementsByClassName('client_variables_available'), function(el) {
+                el.style.display = 'none';
+            });
+        } else {
+            Array.prototype.forEach.call(document.getElementsByClassName('client_variables_unavailable'), function(el) {
+                el.style.display = 'none';
+            });
+        }
+    
+        /* Hide the TOC, which might contain hidden content */
+        Array.prototype.forEach.call(document.getElementsByClassName('md-sidebar--secondary'), function(el) {
+            el.style.display = 'none';
+        });
+    
+        /* Substitute variables */
+        Array.prototype.forEach.call(document.getElementsByClassName('client_var_host'), function(el) {
+            el.innerText = getCookie('host');
+        });
+        Array.prototype.forEach.call(document.getElementsByClassName('client_var_link'), function(el) {
+            if (!getCookie('host')) {
+                el.href = '#';
+            } else if (getCookie('port') != '443') {
+                el.href = 'https://' + getCookie('host') + ':' + getCookie('port') + '/' + el.getAttribute("href");
+            } else {
+                el.href = 'https://' + getCookie('host') + '/' + el.getAttribute("href");
+            }
+        });
+        Array.prototype.forEach.call(document.getElementsByClassName('client_var_email'), function(el) {
+            el.innerText = getCookie('email');
+        });
+        Array.prototype.forEach.call(document.getElementsByClassName('client_var_name'), function(el) {
+            el.innerText = getCookie('name');
+        });
+        if (getCookie('port') != '443') {
+            Array.prototype.forEach.call(document.getElementsByClassName('client_var_port'), function(el) {
+                el.innerText = ':' + getCookie('port');
+            });
+        }
+    
+        /* Hide those sections that are not applicable because useOutlookForEAS is disabled or SOGo integrator is not available */
+        if (getCookie('integrator')) {
+            Array.prototype.forEach.call(document.getElementsByClassName('client_var_integrator_link'), function(el) {
+                el.href = el.href.replace('__DOMAIN__', getCookie('domain')).replace('__VERSION__', getCookie('integrator'));
+            });
+            Array.prototype.forEach.call(document.getElementsByClassName('client_integrator_disabled'), function(el) {
+                el.style.display = 'none';
+            });
+        } else if (getCookie('host')) {
+            Array.prototype.forEach.call(document.getElementsByClassName('client_integrator_enabled'), function(el) {
+                el.style.display = 'none';
+            });
+        }
+        if (getCookie('outlookEAS') || !getCookie('host')) {
+            Array.prototype.forEach.call(document.getElementsByClassName('client_outlookEAS_disabled'), function(el) {
+                el.style.display = 'none';
+            });
+        } else {
+            Array.prototype.forEach.call(document.getElementsByClassName('client_outlookEAS_enabled'), function(el) {
+                el.style.display = 'none';
+            });
+        }
+    }
+}

mkdocs.yml

@@ -15,6 +15,7 @@ markdown_extensions:
   - pymdownx.tasklist(custom_checkbox=true)
   - pymdownx.mark
   - pymdownx.tilde
+  - pymdownx.extra
   - footnotes
 pages:
 - 'Information & Support': 'index.md'
@@ -67,6 +68,16 @@ pages:
   - 'Redirect HTTP to HTTPS': 'u_e-80_to_443.md'
   - 'Adjust Service Configurations': 'u_e-change_config.md'
   - 'Deinstall': 'u_e-deinstall.md'
+- 'Client Configuration':
+  - 'Overview': 'client.md'
+  - 'Android': 'client-android.md'
+  - 'Apple macOS / iOS': 'client-apple.md'
+  - 'eM Client': 'client-emclient.md'
+  - 'KDE Kontact': 'client-kontact.md'
+  - 'Microsoft Outlook': 'client-outlook.md'
+  - 'Mozilla Thunderbird': 'client-thunderbird.md'
+  - 'Windows': 'client-windows.md'
+  - 'Windows Phone': 'client-windowsphone.md'
 - 'Third party apps':
   - 'Roundcube': 'third_party-roundcube.md'
   - 'Portainer': 'third_party-portainer.md'
@@ -82,4 +93,5 @@ extra:
     - type: github-alt
       link: https://github.com/mailcow
 extra_css: [extra.css]
+extra_javascript: [clients.js]
 google_analytics: ['UA-92608422-4', 'mailcow.github.io']