Three mailcow admin chores, solved: SOGo login as a user, backup-first updates, per-domain DNS

The problem: three chores that eat your week

If you run mailcow-dockerized for yourself or a handful of clients, you know the routine. Someone asks you to check a mailbox, so you click SOGo next to it in the admin UI, and your admin session is gone: mailcow keeps one session per host name, so the same session switches to the mailbox. While the admin session is open, SOGo sends you back to the dashboard anyway.

Then there is the update. mailcow releases often, and updating means an SSH session, update.sh, and hoping you remembered a backup. And every new mail domain needs its MX, SPF, DKIM and DMARC records set by hand at the DNS provider, plus a reverse DNS check nobody remembers until Gmail starts rejecting mail.

mailcow Toolkit is a plugin that fixes all three from inside your own mailcow, and it keeps working after mailcow updates because it changes no tracked mailcow file. This tutorial walks through the setup once, so the daily chores become clicks.

Prerequisites

• mailcow-dockerized on Linux (the Toolkit is tested with 2026-09 and 2026-09a), installed for example in /opt/mailcow-dockerized, with docker compose and systemd.
• Root access on the host, with git, jq, flock, curl, tar and sha256sum installed.
• Outgoing HTTPS to medialab.works from the server (license check, trial, Toolkit updates).
• A license key from your medialab.works account, or an e-mail address for the free 30-day trial.
• A second host name for webmail (for example webmail.example.com) in DNS, served by the same reverse proxy as the mailcow UI.
• A backup folder, for example /srv/backup/mailcow.
• For SOGo as a mailbox: ALLOW_ADMIN_EMAIL_LOGIN=y in mailcow.conf and the Login as mailbox user permission.
• Optional, for writing DNS records: a Cloudflare account and an API token with Zone > Zone > Read and Zone > DNS > Edit.

Step 1 — Install the Toolkit

Download mailcow-toolkit-<version>.tar.gz from your account, unpack it on the mailcow host and run, as root:

sudo ./install.sh --mailcow-dir /opt/mailcow-dockerized \
  --webmail-url https://webmail.example.com --backup-dir /srv/backup/mailcow

• --mailcow-dir is where mailcow lives (default /opt/mailcow-dockerized).
• --webmail-url is the webmail address, https:// plus host name (an optional port is allowed). Leave it out and the SOGo button keeps mailcow's stock behavior.
• --backup-dir is where backups before updates go. Leave it out and Update now runs without a backup first, and the installer warns you.
• --name is only needed if you run several mailcow installations on one host.

The installer enables five systemd units, among them a daily timer for the version check and license, one that checks reverse DNS every 6 hours, and one that looks for new mailcow domains every 2 minutes. At the end it reloads php-fpm and asks you to open the License section.

Step 2 — Activate the license

Open System > Updates (Toolkit) as an admin. The License section at the top works even without a license: enter your key and press Activate, or start the free 30-day trial with your e-mail address and open the Stripe checkout link shown (the card is asked there and not charged during the trial). The page activates the Toolkit by itself once the trial starts. Without a valid license the Toolkit features stop and nothing is deleted.

Step 3 — A separate webmail host name

This is the whole trick behind keeping your admin session. Your browser keeps one session cookie per host name, so SOGo needs its own name.

1. Point webmail.example.com at your server in DNS.
2. In your reverse proxy, serve it exactly like the mailcow UI: same backend, same headers. It is the same mailcow, only under another name.
3. Give it a TLS certificate, like the UI.

If you already installed with --webmail-url, this is done. If not, run install.sh again from the new version; your earlier webmail address and backup folder are kept when you leave them out.

Step 4 — Enable SOGo as a mailbox

1. In mailcow.conf set ALLOW_ADMIN_EMAIL_LOGIN=y, then apply it from the mailcow UI.
2. Make sure the admin has the Login as mailbox user permission.

From then on, the SOGo button in the mailbox list (for the platform admin; domain admins keep mailcow's own button) opens SOGo as that mailbox, in a new tab, while your admin tab stays signed in. The hand-off uses a one-time token valid 60 seconds and used once; on the webmail host a fresh mailbox session starts and never inherits the admin role. Inactive mailboxes are refused, following mailcow's own rules.

Every use is logged twice: in mailcow's login log of that mailbox, as an SSO login, and in the Toolkit audit log, with who opened it and from which address. That is the part auditors and clients like.

Step 5 — Backup-first updates from the UI

Open System > Updates (Toolkit). The page shows the installed mailcow version, the last check and the new changes. The server checks for a new mailcow version every day and sends one e-mail per new version to the address you set on the page.

When you are ready, press Update now. The Toolkit first takes a backup (crypt, redis, rspamd, postfix and mysql, kept 14 days), then runs mailcow's own update.sh, then waits until every container is running and the UI answers. The log is shown live on the page.

Two guarantees matter: if the backup fails, the update is stopped and nothing is changed; if update.sh fails or a container does not start, the page says so and keeps the log. The page follows the language of the mailcow UI, English or Romanian.

Step 6 — DNS records for every domain

Open System > DNS & Cloudflare (admins only). For every mailcow domain and alias domain it lists the records mailcow needs, following mailcow's own DNS check:

• Required: the A record of MAILCOW_HOSTNAME (DNS-only in Cloudflare), MX 10 to MAILCOW_HOSTNAME, SPF, DKIM (mailcow's selector and key) and DMARC.
• Recommended: the autodiscover and autoconfig CNAMEs (DNS-only), SRV records for autodiscover, IMAPS, submission, SMTPS, POP3S (when POP3 is allowed), CalDAV and CardDAV with their path=/SOGo/dav/ TXT (with SOGo), and MTA-STS and TLS-RPT when MTA-STS is active for the domain.
• Alias domains get MX, SPF, DKIM, DMARC and, with MTA-STS, its TXT records.

Each record is compared with public DNS, with a zone file you upload (a Cloudflare export or any BIND file) and, with Cloudflare credentials, with the live Cloudflare zone. Statuses are OK, missing, different, proxied (must be DNS-only), fix by hand or unknown.

Two defaults keep you out of trouble. IPv4 only by default: no AAAA record and an SPF of v=spf1 ip4:<IPv4> -all; the Use IPv6 setting adds AAAA, ip6: and the IPv6 reverse DNS check, because a server that publishes AAAA without a matching IPv6 PTR gets its mail over IPv6 rejected by Gmail and others. And DMARC: an existing valid policy is kept; otherwise you get v=DMARC1; p=quarantine;, with reports to dmarc@ or postmaster@ only when that address exists. The SRV ports follow mailcow.conf and can be set by hand for servers behind a proxy or NAT.

Download BIND zone file gives you a file Cloudflare imports under DNS > Records > Import and Export, with cf_tags=cf-proxied:false on records that must stay DNS-only.

Step 7 — Apply to Cloudflare, safely

With a scoped API token (recommended) or the Global API Key, tick records, preview the changes and apply them. A JSON backup of the zone is saved first and the change can be undone; only the selected records are created or updated, nothing is deleted, and every change goes to the audit log. The credentials are checked with Cloudflare, stored encrypted on your server and never shown again. The Cloudflare actions of a domain appear only when the saved credentials may edit DNS in that zone; otherwise the page says why.

Step 8 — Let new domains set themselves up

Two features are off until you configure them:

• Automatic Cloudflare setup: within about 2 minutes of a domain or alias domain being added in mailcow (UI or API), its records are created in the existing Cloudflare zone. Wrong records are updated, unrelated records are never deleted, and an existing different SPF, DMARC or TLS-RPT policy is left as it is. A missing zone is reported, or created if you allow it; failures can be e-mailed to you.
• New domain wizard: the role addresses (postmaster, abuse, hostmaster, webmaster, contact, info, office, dmarc, tls-rpt, noreply, security, each optional, plus your own) are created as aliases to an address you choose, so they do not count against the mailbox limit. noreply@ discards mail silently. An existing mailbox or alias is never touched.

Domains that already exist when you turn a feature on are left alone; Provision now and Run wizard do them one by one.

Step 9 — Watch the PTR and the per-domain status

The Toolkit checks reverse DNS every 6 hours and shows a red "!" in the admin menu when it fails. The DNS page opens with a summary and a selector of every domain and alias domain, worst first: critical (mail cannot be delivered or sent, or will land in spam), warning (optional records missing) or all good, with an explanation of what is wrong and how to fix it for each domain. Statuses refresh every 10 minutes in the background; Re-check now checks a domain at once. The last selected domain is remembered.

Tips and troubleshooting

• SOGo says "Unauthorized" for a new domain. SOGo reads mailcow's domains when it starts, so a domain added later is unknown to it. From 0.4.0 the Toolkit finds such domains every 2 minutes and restarts only the SOGo container (and empties memcached), within about 3 to 10 minutes of the domain being added: once for several new domains, at most every 10 minutes, only with a valid license. Every restart goes to the audit log.
• The SOGo button behaves like stock mailcow. Check that --webmail-url was passed, that ALLOW_ADMIN_EMAIL_LOGIN=y is applied, and that the admin has the Login as mailbox user permission.
• Update now is greyed out or runs without a backup. The backup folder comes from --backup-dir; re-run install.sh to set it.
• A record shows proxied. That record must be DNS-only in Cloudflare; the zone file export marks these with cf_tags=cf-proxied:false.
• Server behind a proxy or NAT. Set the SRV ports by hand on the DNS page; they otherwise follow mailcow.conf.
• No connection to medialab.works. After the last successful check the Toolkit keeps working for 7 days.
• Updating the Toolkit itself. Use the License section: it downloads the signed archive, checks size and SHA-256, and keeps the previous version, so a failed install rolls back. install.sh from a newer version works too.

Conclusion

None of these three chores is hard; they are just easy to forget. A separate webmail host name turns SOGo into a safe, audited, one-click view of any mailbox while your admin session stays open. A backup-first update button removes the SSH step and the guesswork. And a DNS page that compares every domain with public DNS and Cloudflare, plus a PTR check every 6 hours, catches the problems before a recipient does. Because the Toolkit changes no tracked mailcow file, it survives mailcow updates, so you set it up once.

The user guide covers every setting in detail, the changelog lists what each version added, and our knowledge base has more for self-hosters. Questions? Get in touch.