Vendre des boîtes mail et des packs de domaines sur mailcow avec votre compte Stripe

Si vous faites déjà tourner mailcow pour vous-même, on vous a probablement posé la même question plus d'une fois : pourriez-vous aussi héberger le courrier de quelqu'un d'autre ? La partie technique est la plus simple. La plus délicate, c'est la facturation : qui est sur quelle formule, que se passe-t-il quand une carte est refusée, et comment arrêter un compte sans le détruire.

Cashier for mailcow est conçu exactement pour cette moitié-là. Il vend des formules boîte aux lettres et des paquets de domaine sur votre mailcow, payés mensuellement ou annuellement par carte via votre propre compte Stripe, et applique chaque changement à mailcow dès que le paiement est confirmé. Les comptes impayés sont suspendus après un délai de grâce que vous choisissez, jamais supprimés. Ce tutoriel vous guide pour le mettre en place comme une petite activité d'hébergement de messagerie.

Prérequis

Avant de commencer, assurez-vous de disposer de :

• Du paquet mailcow Toolkit 0.4.0 ou plus récent sur mailcow-dockerized (Linux, docker compose, systemd). Cashier est livré dans le paquet et s'installe avec install.sh en root sur l'hôte.
• De Sign-up for mailcow avec sa propre licence valide, configuré, car les comptes payants sont créés via sa page d'inscription.
• D'une clé de licence Cashier for mailcow (une clé du pack mailcow convient aussi) ou d'une adresse e-mail pour l'essai gratuit de 30 jours.
• De votre propre compte Stripe dans un pays pris en charge par Stripe. L'argent, les factures et les données clients restent dans votre compte ; MediaLab Works n'est pas partie à vos ventes.
• D'une interface mailcow accessible depuis internet en HTTPS, pour que Stripe puisse appeler le webhook, ainsi que d'un accès HTTPS sortant vers api.stripe.com et medialab.works pour la vérification de licence.

Étape 1 — Activer la licence

Ouvrez System > Updates (Toolkit) et repérez la carte License · Cashier for mailcow. Saisissez votre clé et appuyez sur Activate, ou lancez l'essai gratuit de 30 jours avec votre adresse e-mail. En ligne de commande, l'équivalent est :

docker compose exec -u www-data php-fpm-mailcow php /web/mlw-toolkit/cli.php activate mailcow-cashier <KEY>

Exécutez-la depuis le dossier mailcow. La licence est vérifiée au démarrage et une fois par jour ; sans internet, Cashier continue de fonctionner pendant 7 jours après la dernière vérification réussie. Sans licence valide, aucun nouveau paiement n'est lancé, mais les webhooks des abonnés existants sont toujours traités et rien n'est supprimé.

Étape 2 — Connecter Stripe

Ouvrez System > Cashier et parcourez la carte Stripe :

1. Dans votre tableau de bord Stripe, créez une clé restreinte (Developers > API keys > Create restricted key) avec un accès en écriture à Customers, Checkout Sessions, Customer portal, Products, Prices, Subscriptions, Subscription items et Webhook Endpoints, et un accès en lecture à Invoices. Une clé secrète fonctionne aussi, mais une clé restreinte est plus sûre.
2. Collez la Publishable key et la Secret / restricted key. Les deux doivent être des clés de test ou toutes deux des clés live ; Cashier les vérifie auprès de Stripe et affiche le compte et le mode. La clé secrète est stockée chiffrée et n'est plus jamais affichée ; laissez donc le champ vide par la suite pour la conserver.
3. Appuyez sur Create the webhook. Cashier enregistre https://<mail host>/mlw-cashier/webhook.php dans votre compte Stripe avec les événements nécessaires et enregistre le secret de signature. Si un proxy réécrit le nom d'hôte, renseignez d'abord Public webhook address sous Rules.
4. Vérifiez Last event pour confirmer que les événements arrivent bien.

Pour passer plus tard du mode test au mode live, connectez les clés live et recréez le webhook.

Étape 3 — Définir vos formules

Dans Plans, appuyez sur New plan. Choisissez le Kind :

• mailbox — une boîte aux lettres avec son quota, pour ceux qui veulent seulement une adresse.
• domain package — pour les administrateurs de domaine : Domains (package), Mailboxes / domain, Aliases / domain, Quota (MB; package: per domain) et Default quota / mailbox (MB).

Renseignez ensuite les noms et descriptions en anglais et en roumain (ils apparaissent sur la page d'inscription dans la langue du visiteur), un prix mensuel et/ou un prix annuel dans la devise de votre compte Stripe, ainsi que les jours d'essai (0 = aucun). Cashier crée le produit et les prix dans votre compte Stripe pour vous. Laissez Visible on the registration page coché pour les formules publiques ; décochez-le pour une formule cachée accessible uniquement via son lien direct (/mlw-signup/?plan=<token>) ou un code d'invitation lié à la formule.

Edit modifie une formule : un montant modifié crée un nouveau prix dans Stripe et désactive l'ancien, que les abonnés existants conservent. Archive retire une formule de la vente sans toucher à ses abonnés.

Étape 4 — Ajouter des extensions

Dans Add-ons, créez les extras que les clients peuvent acheter en quantité : des boîtes aux lettres supplémentaires sur chaque domaine du paquet, ou du stockage supplémentaire (Mo par domaine ; sur une formule boîte aux lettres, par boîte aux lettres). Définissez l'Unit, les noms, les prix mensuels et annuels et Visible. Les clients les ajoutent dans My account ; Stripe calcule le prorata et les nouvelles limites sont appliquées à mailcow immédiatement.

Étape 5 — Fixer les règles : délai de grâce et suspension

Sous Rules, décidez de votre niveau de rigueur :

• Grace period after a failed payment (days, 0–90) — la valeur par défaut est de 7 jours, pendant lesquels le compte continue de fonctionner pendant que le client paie.
• After the grace period the account is suspended — choisissez no sign-in: mail is still received (par défaut) ou inactive: mailboxes, domain administrator and domains. Rien n'est jamais supprimé, et un paiement rétablit le compte immédiatement.
• E-mail the subscribers about invoices and receipts.
• Public webhook address (empty = automatic), Stripe product tax code et Stripe name prefix — ce dernier compte lorsque plusieurs serveurs mailcow partagent un même compte Stripe.

Pour une petite activité d'hébergement, le mode par défaut sans connexion est un bon point de départ : un client en défaut cesse d'utiliser le service, mais le courrier continue d'arriver, donc rien n'est perdu et un paiement réactive tout.

Étape 6 — Savoir ce que voient les clients

Sur la page d'inscription, un visiteur choisit une formule (mensuelle ou annuelle), confirme son adresse et paie sur la page de paiement Stripe. Le compte est créé lorsque Stripe confirme le paiement. Dans My account, il voit la formule, la date du prochain paiement et les extensions, peut utiliser Change plan (au prorata ; une formule inférieure à l'utilisation actuelle est refusée, avec ce qu'il faut réduire d'abord) et ouvrir Card, invoices and cancellation (Stripe), le portail client Stripe.

Un paiement échoué envoie un e-mail avec le lien de paiement et la date de suspension. Un client suspendu qui ne peut pas se connecter peut demander le lien de paiement depuis la page publique /mlw-cashier/billing.php en saisissant l'adresse e-mail du compte. Une résiliation prend effet à la fin de la période payée, et le compte créé par l'abonnement reste alors suspendu.

Étape 7 — Gérer le côté administrateur

Subscribers liste chaque abonnement avec son état (active, grace, suspended, ended), la formule, le montant, le lien vers Stripe et le Monthly revenue, ainsi que les Recent Stripe events reçus par le webhook. Grant a plan for free offre une formule à un compte pour un nombre de jours sans Stripe, et un octroi peut être terminé avant terme — pratique pour tester ou pour rendre service à un ami.

Les formules, clients et abonnements vivent dans la base de données de mailcow (tables mlw_ca_*) et font donc partie des sauvegardes de mailcow. Les clés et le secret du webhook se trouvent dans le dossier partagé du Toolkit, chiffrés avec AES-256-GCM, la clé de chiffrement étant conservée à part dans le redis de mailcow.

Conseils et dépannage

• Le webhook n'arrive pas ? Vérifiez Last event dans la carte Stripe. Si un reverse proxy réécrit le nom d'hôte, renseignez la Public webhook address sous Rules et recréez le webhook.
• Clés refusées ? Assurez-vous que les deux clés sont de test ou toutes deux live ; les mélanger fait échouer la vérification.
• Un client veut une formule plus petite, mais elle est refusée. C'est intentionnel : rien n'est supprimé pour la faire rentrer. Demandez-lui de retirer d'abord des boîtes aux lettres ou du stockage.
• Un événement Stripe répété. Les événements sont vérifiés par signature et traités une seule fois ; un doublon ne change donc rien.
• La vérification de licence échoue. Le serveur doit joindre medialab.works en HTTPS ; Cashier continue de fonctionner pendant 7 jours après la dernière vérification réussie.
• Changement de serveur. uninstall.sh retire Cashier avec le Toolkit mais conserve les tables et tous les comptes ; les clés chiffrées partent avec le dossier partagé, prévoyez donc une reconnexion de Stripe ensuite.

Conclusion

Cashier for mailcow ne cherche pas à être une plateforme de facturation complète. Il fait bien une chose : vendre des boîtes aux lettres et des paquets de domaine sur votre propre mailcow, via votre propre compte Stripe, avec des changements au prorata, un délai de grâce que vous contrôlez et une suspension qui ne supprime jamais de données. Consultez le guide utilisateur pour chaque champ, le changelog avant de mettre à jour, et la base de connaissances ou la FAQ en cas de doute. Les questions sur votre configuration sont bienvenues via le contact.