Sign-up for mailcow — guide

Before you start

The mailcow Toolkit package 0.4.0 or newer, installed with install.sh as described in the mailcow Toolkit guide. Sign-up for mailcow is part of the package: there is nothing else to download.
Your Sign-up for mailcow license key, from your medialab.works account (a mailcow bundle key works too), or an e-mail address for the free 30-day trial.
Outgoing HTTPS to medialab.works from the server (license check) and a mailcow that sends e-mail (confirmation, approval and welcome e-mails).
At least one mailcow domain to open for registration, if visitors should get mailboxes.

Installation and updates

install.sh from the package (0.4.0 or newer) installs Sign-up next to the Toolkit: the web files in mailcow's data/web/mlw-signup, the settings folder, the tables mlw_su_* in mailcow's database and the timer mlw-mailcow-accounts-<name>.timer, which runs the Sign-up and Cashier jobs every 5 minutes. A Toolkit already installed gets all this when you update it to 0.4.0 from System > Updates (Toolkit) or run the new install.sh. Sign-up stays switched off until it is licensed and you open registrations.

Sign-up is updated together with the Toolkit: one package, one update. The update can be started from the License card of any product with a valid license.

License and free trial

Open System > Updates (Toolkit) (admins only). From 0.4.0 the page shows one License card per product; use the card License · Sign-up for mailcow:

Enter your license key and press Activate, or start the free 30-day trial with your e-mail address: the card is asked on the Stripe checkout page and not charged during the 30 days, and the card activates Sign-up by itself as soon as the trial starts. Each mailcow tool has its own trial, once per server and per e-mail address.
With a mailcow bundle key, enter the same key in each product's License card.
On the shell: docker compose exec -u www-data php-fpm-mailcow php /web/mlw-toolkit/cli.php activate mailcow-signup <KEY> from the mailcow folder.

The license is checked when the server starts and once a day; without internet Sign-up keeps working for 7 days after the last successful check. Without a valid license registrations close (the public page says that registration is not available) and the background jobs stop for Sign-up; existing accounts, mailboxes and domains are never touched.

Opening registrations

Open System > Sign-up. The Registration card holds the main choices; save the form with the button at its end.

Registrations open — turns the public page /mlw-signup/ on. mailcow's sign-in page then shows the Create an account link (on the UI and on the webmail host name).
A mailbox on one of your domains — tick it and choose the Domains open for registration. Set Min. characters and Max. characters for the name before the @, the Free quota (MB), More reserved names (role names such as postmaster, abuse, admin, support and noreply are always reserved) and the mailcow mailbox template (empty = mailcow's default).
A domain administrator for the customer's own domains — the customer adds domains after a DNS (TXT) check, within the package limits. The Free package sets Domains, Mailboxes/domain, Aliases/domain, Quota/domain (MB) and Default quota/mailbox (MB); the mailcow domain template is used for new customer domains. With the option about the new domain wizard, the Toolkit's wizard creates the role addresses of a customer domain to the customer's e-mail.
Free registration (next to Cashier's paid plans) — leave it ticked for free accounts; untick it when every account must buy a plan with Cashier for mailcow.

Confirmation, approval and invitations

In the card Confirmation, approval, invitations:

Address confirmation — 6-digit code, link, code and link, or none (not recommended). Expires (hours) — from 1 to 168. A visitor can ask for a new e-mail after a minute, at most 5 times a day, and has 5 attempts per code.
Administrator approval — free registrations wait for an administrator; set E-mail for registrations to approve to be told of each new one. Paid registrations are never held for approval.
Invitation code — off, optional or required.
Terms link (asks for acceptance) — a link to your terms; the visitor must accept them.
Form fields — name, company, phone and country: off, optional or required.

Approving registrations

The card Registrations lists those Waiting for approval. Approve creates the account and sends the welcome e-mail; Reject (with an optional Reason) sends the visitor an e-mail with the decision. Recent shows the latest registrations and their state.

Invitation codes

In Invitation codes fill in Code (empty = random), Uses (0 = unlimited), Expires, the Account kind (mailbox, domain or any) and, with Cashier, the Plan the code opens (including a hidden one), tick No approval if the code should skip the approval, add a Note and press Create the code. The list shows how often each code was used; Disable and Enable switch it off and on.

Anti-abuse

In the card Anti-abuse:

Minimum time to fill in (s) — a form sent faster is refused (bots). A hidden field catches the simplest bots on its own.
Registrations / IP / day (0 = no limit).
Block disposable addresses — the built-in list plus the MediaLab Works list, which arrives with the license check while the license is valid.
Only these e-mail domains (empty = any) and Blocked e-mail domains — separated by spaces, commas or new lines. A domain also covers its subdomains; *.example.com means the subdomains only.
The password must follow mailcow's own password policy, the one set in mailcow's admin UI.

New accounts

In the card New accounts: Own text in the welcome e-mail (English and Romanian), the Sender name of the e-mails (empty = the mail host name) and Sign in the browser that registered (on by default).

A free mailbox is created as soon as the address is confirmed (and approved). A domain administrator is created with the first verified domain: until then the customer has a page, My account, where the next step is to add the domain.

The customer's own domains

The customer opens My account (/mlw-signup/account.php, also in the mailcow menu while signed in) and adds a domain. The page shows a TXT record to publish at the customer's DNS provider:

_mlw-verify.example.com.  TXT  "mlw-verify=<token>"

Verify checks it at once; Sign-up also checks every 10 minutes for 7 days. When the record is found, the domain is added to mailcow with the package limits, and the page shows the DNS records of the domain (required and recommended) the customer must set: MX, SPF, DKIM, DMARC, autodiscover and the others, computed by the Toolkit's DNS module. An administrator can check one domain from the shell, in the mailcow folder: docker compose exec -u www-data php-fpm-mailcow php /web/mlw-signup/cli.php verify example.com.

Customer domains are kept out of your own Cloudflare automatic setup (the customer manages their own DNS).

Data, backups and removal

The registrations, customers and invitation codes are in mailcow's database (tables mlw_su_*), so they are in mailcow's backups. The settings are in the Toolkit's shared folder.
The timer mlw-mailcow-accounts-<name>.timer runs every 5 minutes: it removes expired registrations and checks pending customer domains.
uninstall.sh removes Sign-up with the Toolkit, but keeps the tables and every mailbox, domain and domain administrator created through it.

Common problems

The sign-in page shows no "Create an account" link. Registrations are closed, the license is not valid, or no account kind is offered (no domain open for mailboxes and no domain administrator). Check the License card and System > Sign-up.

The public page says registration is not available. Same causes: the license (see the message on the License card) or Registrations open.

Visitors receive no confirmation e-mail. Check that mailcow delivers outgoing mail (the e-mails are sent through mailcow) and the spam folder. After 5 e-mails in a day the address must wait until the next day.

A customer domain stays "Waiting for verification". The TXT record is missing, has another value or has not propagated yet. Check it with dig TXT _mlw-verify.example.com. After 7 days the automatic checks stop; Verify still works.

A domain was refused. It is already on this server, another account is adding it, or the customer's package has no free domain left (a bigger plan with Cashier allows more).