Héberger la messagerie

Kuploy Cloud comporte un hébergement de messagerie intégré, propulsé par Stalwart Mail Server. Vos organisations peuvent ainsi créer des boîtes aux lettres sur leurs propres domaines personnalisés — utilisateur@societe.com, par exemple.

Ces boîtes sont accessibles en IMAP/SMTP depuis les logiciels de messagerie de bureau et mobiles, ou — en option — par un webmail dans le navigateur. Voir Webmail pour activer un lien « Open Webmail » sur la page Mailboxes et configurer l'autoconfiguration des clients de bureau et mobiles.

Vue d'ensemble

L'hébergement de messagerie est une fonctionnalité conditionnée par l'offre. C'est votre abonnement kuploy.app qui détermine s'il est disponible, et combien de boîtes aux lettres chaque offre autorise :

Offre	Fonctionnalité	Limite de boîtes
Hobby	Non	0
Starter	Oui	10
Growth	Oui	50
Business	Oui	200
Enterprise	Oui	Illimité

Le nombre de boîtes est suivi par instance et rapporté à kuploy.app lors de la synchronisation de licence. L'application des quotas est la même que pour les autres ressources : avertissement à 80 %, blocage ferme à 100 %.

L'architecture

┌─────────────┐     SMTP/IMAP     ┌───────────────────┐
│  Logiciel de │ ◄──────────────► │  Stalwart Mail     │
│  messagerie  │                   │  Server            │
│ (Thunderbird,│                   │  (ports 25,587,    │
│  Outlook)    │                   │   993,4190)        │
└─────────────┘                   └─────────┬─────────┘
                                            │ API REST
                                  ┌─────────▼─────────┐
                                  │  kuploy-cloud      │
                                  │  (mise en service) │
                                  └─────────┬─────────┘
                                            │ synchro de licence
                                  ┌─────────▼─────────┐
                                  │  kuploy.app        │
                                  │  (suivi des quotas)│
                                  └───────────────────┘

• Stalwart se charge du SMTP (envoi et réception), de l'IMAP (accès aux boîtes) et de Sieve (le filtrage).
• kuploy-cloud met en service les comptes et les domaines, via l'API REST de Stalwart.
• kuploy.app suit le nombre de boîtes aux lettres, dans le cadre du système de quotas de licence.

Mise en place

1. Déployer Stalwart

Stalwart tourne comme un StatefulSet, aux côtés de votre instance kuploy-cloud. Déployez-le avec le déployeur kuploy-k8s :

python deploy.py stalwart \
  --mail-hostname mail.example.com \
  --postgres-service pg-postgresql-0.pg-postgresql-headless \
  --db-namespace database \
  --storage-class longhorn \
  --stalwart-lb-ip <ip-dédiée> \
  --stalwart-storage 100Gi

Ou bien incluez-le dans un déploiement complet, avec --mail-hostname :

python deploy.py --edition cloud --domain console.example.com \
  --mail-hostname mail.example.com

Pour un déploiement Docker Compose, ajoutez Stalwart comme service, avec les ports 25, 587 et 993 exposés.

2. Créer une clé d'API

kuploy-cloud dialogue avec Stalwart par son API REST, au moyen d'une clé d'API (jeton Bearer).

1. Accédez à l'interface web de Stalwart (par une redirection de port au besoin : kubectl port-forward svc/stalwart-api -n kuploy 8080:8080)
2. Connectez-vous avec le mot de passe d'administration, affiché dans les journaux du pod Stalwart à son premier démarrage
3. Allez dans Directory → API Keys → Create API Key
4. Copiez le jeton Bearer depuis l'onglet Authentication — il commence par api_
5. Dans l'onglet Permissions, passez toutes les permissions requises sur On, et non sur Default :
   • Create/Remove/View/Modify principals
   • Add/Remove/View email domains
   • Create/Retrieve DKIM signatures
   • Authenticate

attention

Les permissions d'une clé d'API Stalwart sont refusées par défaut. « Default » ne signifie pas « héritée de l'administrateur ». Vous devez basculer explicitement chacune sur « On ».

3. Configurer la connexion

Renseignez l'URL et la clé de l'API dans votre instance kuploy-cloud. Deux méthodes, à votre convenance :

Option A : le tableau de bord d'administration (recommandé)

Allez dans Admin → Email Hosting (Stalwart) (/admin/mail), saisissez l'URL et la clé de l'API, puis cliquez sur Test Connection pour vérifier.

Réglage	En production	En développement local
URL de l'API	http://stalwart-api.kuploy:8080	http://localhost:8080 (avec une redirection de port)
Clé d'API	Le jeton Bearer de l'étape 2	Le même

Option B : les variables d'environnement

Variable	Description	Exemple
STALWART_API_URL	L'URL de base de l'API de gestion de Stalwart	http://stalwart-api:8080
STALWART_API_TOKEN	La clé d'API : le jeton Bearer de Directory → API Keys	api_abc123...

Les réglages du tableau de bord ont priorité sur les variables d'environnement, lorsqu'ils sont renseignés.

La page d'administration de la messagerie affiche aussi une carte Live Server Status, qui interroge Stalwart toutes les 30 secondes et rapporte son accessibilité, sa latence, sa version et la profondeur de sa file. Servez-vous-en pour confirmer que la connexion est saine, avant de mettre des boîtes en service.

astuce

Sans ces réglages, l'interface des boîtes aux lettres fonctionnera tout de même pour gérer les enregistrements en local, mais aucun courriel ne sera réellement acheminé. Cela vous permet de préconfigurer domaines et boîtes avant que Stalwart ne soit prêt.

Le déchiffrement du jeton échoue après le partage d'une base

Si vous faites tourner deux déploiements — production et développement, par exemple — sur la même base de données, tous deux doivent utiliser le même APP_SECRET. Le jeton d'API de Stalwart est chiffré avec APP_SECRET ; si le secret diffère, le second déploiement ne peut pas le déchiffrer et la page de messagerie affiche une alerte « token decryption failed ». Alignez APP_SECRET entre vos déploiements, ou réenregistrez la configuration sur chacun pour la rechiffrer avec la clé locale.

4. La configuration DNS

Chaque domaine de messagerie exige les enregistrements DNS suivants. Le tableau de bord kuploy-cloud affiche les enregistrements exacts à créer dès qu'un domaine est ajouté :

Enregistrement	Hôte	Valeur
MX	example.com	10 mail.votre-instance.kuploy.cloud
TXT	example.com	v=spf1 a mx include:mail.votre-instance ~all
TXT	kuploy._domainkey.example.com	v=DKIM1; k=rsa; p=<clé-publique>
TXT	_dmarc.example.com	v=DMARC1; p=quarantine; rua=mailto:postmaster@example.com

Après avoir créé ces enregistrements, utilisez le bouton Verify du tableau de bord pour contrôler la propagation DNS.

5. Pare-feu et répartiteur de charge

Assurez-vous que les ports suivants sont joignables depuis Internet :

Port	Protocole	Rôle
25	TCP	SMTP (réception)
587	TCP	Soumission SMTP
993	TCP	IMAPS (accès aux boîtes)

6. (Facultatif) Le webmail

Si vous voulez offrir à vos utilisateurs finaux un client de messagerie dans le navigateur, déployez un webmail (Roundcube, SOGo, ou tout webmail sachant parler IMAP/SMTP) aux côtés de Stalwart, et renseignez son URL publique sur /admin/mail. Cette même page d'administration documente aussi les points d'accès d'autoconfiguration que kuploy-cloud sert à Thunderbird, Outlook et Apple Mail. Voir la page Webmail pour la marche à suivre complète.

L'application des quotas

Les limites de boîtes aux lettres fonctionnent comme celles des autres ressources :

1. Au niveau de la licence (cumulé) — kuploy.app applique le total sur l'ensemble de vos instances
2. Au niveau de l'organisation (par offre) — le modèle d'offre attribué à l'organisation fixe un plafond par organisation
3. Avertissement à 80 %, blocage ferme à 100 %
4. Les notifications de consommation partent par les canaux de notification que vous avez configurés : courriel, Slack, Discord, etc.

La configuration des modèles d'offre

À la création des modèles d'offre destinés à vos clients, vous pouvez régler la limite mailboxes et l'interrupteur de fonctionnalité mailboxes :

• L'interrupteur (mailboxes: true) — active la section Email Hosting dans le tableau de bord du client ;
• La limite (mailboxes: N) — le nombre maximal de boîtes que l'organisation peut créer ;
• mailboxes: -1 pour un nombre illimité.

Tout cela se configure dans la section Billing > Plan Templates du tableau de bord kuploy.app.

Le suivi

Le nombre de boîtes aux lettres apparaît :

• sur la page Billing de kuploy.app — sous forme d'anneau de consommation, aux côtés des autres ressources ;
• dans les avertissements de synchronisation de licence — à l'approche de 80 % ou 90 % de la limite ;
• dans la consommation par organisation — visible dans la section Organizations du tableau de bord kuploy.app.