Les domaines personnalisés

Branchez un domaine unique pour alimenter le courriel à vos couleurs — envoyer factures, devis et relances depuis noreply@acme.sn — et l'hébergement de la vitrine publique : vos visiteurs parcourent https://acme.sn, et non https://leeram.co/store/acme. Les deux surfaces, pour un seul enregistrement sur /settings/domain.

C'est le signal « ceci n'est pas vraiment à nous » le plus criant que ressentent vos clients dans le produit, et le déclencheur de montée en gamme le plus courant lorsqu'une PME cherche son premier niveau payant.

Disponibilité

Disponible aujourd'hui sur les déploiements leeram-business — la plateforme multi-organisations pour PME. Le courriel passe par le compte Brevo maître de kuploy.app ; le rattachement du nom d'hôte de la vitrine s'opère sur le projet Vercel du déploiement lui-même. Vous ne configurez aucun compte Brevo vous-même : l'enregistrement du domaine d'expédition, la signature DKIM et le traitement des rejets ont tous lieu sur kuploy-hub.

Pour les autres produits — kuploy-cloud, etc. —, voir Configurer le SMTP ou Héberger la messagerie : ceux-là emploient un chemin SMTP ou Stalwart distinct, propre à chaque exploitant.

Comment cela fonctionne

propriétaire de l'org → /settings/domain
                      ↓
        ☑ courriel à vos couleurs   ☑ vitrine publique
                      ↓
          biz → POST kuploy-hub/api/v1/email/domains
                      ↓
        ┌─ centre : Brevo create-sender-domain (courriel)
        ├─ centre : CNAME Vercel sur la zone parente (les deux)
        └─ biz : rattachement du domaine au projet Vercel (vitrine)
                      ↓
        émission du certificat + validation DNS (~15 min)
                      ↓
   le courriel sortant signe contre acme.sn (DKIM)
   les visiteurs sur https://acme.sn → /store/<orgslug>

Vous ne voyez aucune clé d'API Brevo, et n'avez jamais besoin de vous connecter à un tableau de bord Brevo. Les rejets, les plaintes et les désabonnements sont traités de façon centralisée ; la réputation se mutualise entre tous les déploiements qui passent par le compte maître.

La mise en place, côté exploitant

Jusqu'à quatre choses sur votre déploiement, selon ce que vous voulez proposer :

1. Choisissez votre transport de courriel

À définir sur l'hôte de votre déploiement biz — les variables du projet Vercel, ou là où réside la configuration de votre exécution :

MAIL_PROVIDER=hub      # ou « brevo » / « smtp » — voir plus bas

MAIL_PROVIDER décide où part le courriel transactionnel sortant. Les trois valeurs sont des options de plein droit ; choisissez selon que vous voulez des couleurs par organisation, ou un expéditeur unique pour tout le déploiement.

Valeur	Chemin	Expéditeur	À choisir quand
hub	biz → kuploy-hub → le Brevo maître	Par organisation : une ligne org_domain vérifiée donne les couleurs de l'organisation ; sinon, le MAIL_FROM du centre sert de recours	Vous voulez cette fonctionnalité — un courriel aux couleurs de chaque organisation
brevo	biz → votre propre compte Brevo (BREVO_API_KEY)	Le MAIL_FROM du déploiement — aucune personnalisation par organisation	Vous voulez exploiter votre propre Brevo, sans passer par le centre
smtp	biz → votre propre serveur SMTP (SMTP_HOST, etc.)	Le MAIL_FROM du déploiement	Vous avez déjà un relais SMTP que vous préférez utiliser
(non définie)	journalisation seule	—	Développement local ou prévisualisation, sans secrets de production

Pour le reste de ce guide, nous supposons MAIL_PROVIDER=hub : c'est le seul chemin qui mette à l'épreuve la recherche d'org_domain par organisation. Avec brevo ou smtp, les enregistrements de /settings/domain fonctionnent toujours — un exploitant peut enregistrer un domaine, le centre vérifie toujours le DKIM, etc. — mais le courriel sortant emploie l'expéditeur du déploiement, et non l'adresse aux couleurs de l'organisation. Vous pouvez basculer d'un réglage à l'autre à tout moment, sans perdre vos enregistrements.

Avec MAIL_PROVIDER=hub, la clé de licence est lue depuis la ligne license_cache synchronisée que remplit votre parcours de rattachement existant : aucun nouveau secret à gérer. La BREVO_API_KEY de biz devient inutile, le centre détenant la clé maîtresse ; vous pouvez la laisser définie ou la retirer.

2. Les interrupteurs d'offre pour les domaines personnalisés (organisations payantes seulement)

Pour qu'une organisation payante puisse enregistrer un domaine personnalisé qui lui appartient (acme.sn, acmetrading.com, etc.), l'offre à laquelle elle a souscrit doit comporter :

• customEmailDomain: true — le courriel aux couleurs de l'organisation, sur un domaine personnalisé ;
• customDomain: true — la vitrine publique, sur un domaine personnalisé.

D'emblée, les offres amorcées accordent customEmailDomain à partir de Starter, et customDomain sur la seule offre Pro.

3. Les sous-domaines aux couleurs de l'organisation, en offre gratuite (facultatif, recommandé)

À définir côté centre, exploitant par exploitant, dans Admin → Tenants → <identifiant de l'exploitant> → Free zone :

leeram.co

Lorsqu'elle est définie, toute organisation — payante ou gratuite — peut enregistrer <orgslug>.<zone> comme domaine. La valeur descend par l'enveloppe de synchronisation de licence ; biz la lit sans aucune variable locale. Recours pour l'existant : la variable d'environnement BRANDED_EMAIL_FREE_ZONE, sur biz, fonctionne encore si vous n'avez pas migré vers la valeur stockée sur le centre.

4. Le rattachement de la vitrine au projet — le VERCEL_PROJECT_ID de biz

Pour les vitrines sur domaine personnalisé, votre déploiement biz doit indiquer au centre à quel projet Vercel rattacher le nom d'hôte. À définir sur votre déploiement biz :

• VERCEL_PROJECT_ID — l'identifiant du projet Vercel de biz lui-même. Ce n'est pas un secret, seulement un identifiant (par exemple prj_xxxxxxxxxxxxxxxx). Le centre se sert de ses propres identifiants pour appeler POST /projects/:id/domains en votre nom : votre déploiement biz ne détient jamais de jeton Vercel en écriture.

Lorsque VERCEL_PROJECT_ID n'est pas définie sur biz, l'interrupteur de vitrine de /settings/domain est désactivé ; l'enregistrement pour le seul courriel continue de fonctionner.

Le DNS automatique sur la zone parente — et le rattachement au projet lui-même — sont pris en charge côté centre, avec les identifiants de celui-ci, et n'exigent aucune mise en place sur votre déploiement biz au-delà de ce seul identifiant : kuploy.app gère ce versant, au titre de la plateforme.

Le déroulé, surface par surface

Ce qui se passe au clic sur Register domain, lorsque les deux surfaces sont activées :

biz POST /api/v1/email/domains  { orgId, domain, usage:"both",
                                  vercelProjectId: $VERCEL_PROJECT_ID }
                       │
                       ▼
centre : Brevo create-sender-domain  (renvoie DKIM/DMARC/brevo-code)
   ├── écriture DNS automatique des enregistrements Brevo, sur la zone parente
   ├── écriture DNS automatique de l'enregistrement A de la vitrine, sur la zone parente
   └── rattachement de <domain> au projet Vercel de biz (émission du certificat)
                       │
                       ▼
centre : insertion d'org_domain { emailStatus: "pending_dns",
                          storefrontStatus: pending_dns
                          → "verified" quand DNS et rattachement ont tous deux réussi }
                       │
                       ▼
biz : synchronisation de licence après l'action ; le cache de biz prend la nouvelle ligne
                       │
                       ▼
la tâche d'auto-vérification interroge Brevo → emailStatus → "verified"
le certificat Vercel est émis (~30 s) → le rattachement du nom d'hôte est actif dans le middleware

La mise en place, côté propriétaire de l'organisation

Ce que fait un propriétaire d'organisation, une fois la fonctionnalité activée sur son offre :

1. Il ouvre Settings → Domain.
2. Il choisit un mode, quand les deux sont disponibles :
   • Free subdomain — prérempli avec l'identifiant de l'organisation, par exemple acme-trading-co.leeram.co. Aucun travail DNS n'est nécessaire.
   • Custom domain — il saisit le sien (acme.sn). Cela exige le ou les interrupteurs d'offre correspondants, et un accès DNS chez son bureau d'enregistrement.
3. Il coche les surfaces qu'il veut :
   • Branded email — les courriels partent de <partieLocale>@<domaine>.
   • Public storefront — ses visiteurs l'atteignent sur https://<domaine>.
4. Il vérifie que l'aperçu en direct de l'expéditeur et de la vitrine correspond bien à ce qu'il veut.
5. Il clique sur Register domain.

Ce qui suit dépend de la capacité du DNS automatique à écrire sur la zone parente :

Le chemin automatique — zone gratuite, joignable par Vercel : les enregistrements sont écrits aussitôt. La tâche planifiée interroge Brevo tous les quarts d'heure ; l'émission du certificat, du côté vitrine, s'achève dans la minute qui suit la propagation DNS. Vous n'avez plus rien à faire.

Le chemin manuel — domaine personnalisé, Vercel ne gérant pas votre zone : la page affiche quatre enregistrements pleinement qualifiés à publier chez votre fournisseur DNS.

Objet	Type	Surface
brevo_code	TXT	courriel
dkim1Record	CNAME	courriel (la clé de signature DKIM)
dkim2Record	CNAME	courriel (la rotation DKIM)
dmarc_record	TXT	courriel (la politique en cas d'échec d'authentification)
(vitrine)	CNAME → cname.vercel-dns.com	vitrine

Ajoutez-les, puis cliquez sur Verify email — ou attendez la tâche planifiée. Le certificat de la vitrine est émis automatiquement dès que le DNS résout.

Vérifier que cela fonctionne

Un essai de bout en bout, en cinq minutes :

1. Ouvrez /settings/domain en tant que propriétaire d'une organisation payante. Le formulaire doit s'afficher avec les bons interrupteurs actifs, selon l'offre de l'organisation.
2. Déroulez un enregistrement avec un domaine d'essai. Un sous-domaine de la zone gratuite convient très bien — acme-test.votredomaine.com.
3. Le courriel : la ligne passe à emailStatus: verified dans le quart d'heure — ou cliquez sur Verify email. Envoyez une facture d'essai, et inspectez ses en-têtes : From: …@acme-test.votredomaine.com, DKIM-Signature: d=acme-test.votredomaine.com, Authentication-Results: dkim=pass.
4. La vitrine : ouvrez https://acme-test.votredomaine.com dans un navigateur. Elle doit servir la vitrine de l'organisation, avec un certificat TLS valide.

Ce que voient vos clients

Après vérification, tout message sortant part ainsi :

From: Acme Trading <noreply@acme.sn>
DKIM-Signature: v=1; a=rsa-sha256; d=acme.sn; ...
Authentication-Results: dkim=pass d=acme.sn

Et tout lien public que produit l'organisation — les boutons de partage de /catalog, les balises og:url et canoniques de la page de vitrine, le bouton View order & pay des courriels de confirmation de commande, le lien Open this quote / invoice des courriels de devis et de facture, la relance, les entrées du plan de site — pointe vers l'origine aux couleurs de l'organisation :

https://acme.sn/                       (la vitrine)
https://acme.sn/<itemId>               (le lien direct vers un article du catalogue)
https://acme.sn/q/<token>              (le partage d'un devis)
https://acme.sn/i/<token>              (le partage d'une facture)

Ces URL sont stockées sous leur forme canonique (${APP_URL}/store/<slug>, /q/<token>, /i/<token>) ; le basculement vers l'origine personnalisée a lieu au rendu. Si l'exploitant retire le domaine personnalisé plus tard, tout affichage ancien retombe donc proprement sur l'apex — et les courriels envoyés la veille sur l'origine personnalisée conservent leurs liens personnalisés jusqu'à la suppression de la ligne ; le lien renvoie alors un 404, comme n'importe quel message personnalisé expiré.

Le parcours du sous-domaine de vitrine (acme-trading-co.leeram.co) bénéficie du même traitement : le middleware laisse passer /q/*, /i/*, /api/*, /_next/*, /robots.txt, /sitemap.xml et /favicon.ico sans réécriture, afin que les routes de partage par jeton se résolvent proprement sur l'hôte personnalisé, sans exiger un préfixe /store/<slug> par organisation dans le corps du courriel.

Et les visiteurs de https://acme.sn voient la vitrine de l'organisation sous son propre domaine, entièrement protégée par un certificat — sans aucun leeram.co dans la barre d'adresse.

Les réponses continuent d'aller à l'auteur de l'envoi : l'adresse de l'utilisateur pour les envois qu'il a lui-même déclenchés, et aucune remise pour les relances automatiques.

Le comportement du Reply-To

Type d'envoi	Reply-To
À l'initiative de l'utilisateur (envoi d'un devis ou d'une facture)	L'adresse de l'utilisateur lui-même
Par tâche planifiée (relances, factures récurrentes)	Non défini — les réponses sont rejetées

Comme avant l'arrivée du courriel aux couleurs de l'organisation.

Le comportement en cas de rétrogradation

Si vous rétrogradez l'offre d'une organisation vers un niveau dépourvu des interrupteurs correspondants :

• le courriel sortant de cette organisation retombe immédiatement sur l'expéditeur par défaut : votre MAIL_FROM, ou le noreply@kuploy.app de kuploy-hub ;
• l'enregistrement de vérification reste intact sur le centre — réactiver la fonctionnalité rétablit l'envoi aux couleurs de l'organisation, sans nouvelle vérification ;
• l'URL de la vitrine cesse de résoudre sur l'hôte personnalisé : le certificat Vercel demeure, mais la recherche ne trouve plus de ligne vérifiée dans le cache synchronisé, et le middleware ne réécrit donc pas.

Repartir de zéro

Si vous avez enregistré le mauvais domaine — une coquille, un client parti —, la remise à zéro propre est le bouton Remove, sur /settings/domain. Il démonte, dans cet ordre : l'expéditeur Brevo, le domaine d'expédition Brevo, les enregistrements CNAME Vercel, le détachement du domaine du projet Vercel de biz, puis la ligne org_domain.

Vous pouvez alors réenregistrer sur une table rase. Le formulaire conserve le nom affiché par défaut de l'organisation.

Les modes de défaillance

Ce que vous voyez	Cause	Correctif
L'état du courriel reste pending_dns plus d'une heure	Le DNS ne s'est pas propagé	Faites un dig sur les enregistrements pour confirmer ; la tâche planifiée réessaie tous les quarts d'heure
L'état du courriel est failed	Brevo a rejeté la validation	Vérifiez les valeurs DNS ; cliquez sur Verify email pour réessayer
L'URL de la vitrine ouvre la page d'accueil marketing de l'apex	Le storefrontStatus de la ligne orgDomain est pending_dns : le middleware de biz ne réécrit donc pas le nom d'hôte. Cela se produit lorsque le DNS automatique ou le rattachement au projet a échoué à l'enregistrement.	Lisez le bandeau affiché après l'enregistrement : il donne la raison réelle (DNS automatique sauté, VERCEL_PROJECT_ID absente, projet dans une autre équipe). Corrigez la cause, puis faites Remove et réenregistrez.
L'URL de la vitrine renvoie « Deployment not found »	Le centre n'a pas pu rattacher le domaine au projet Vercel de biz	Vérifiez que VERCEL_PROJECT_ID est correctement définie sur biz. Le bandeau affiché après l'enregistrement donne la raison réelle (projet introuvable, déjà utilisé ailleurs, etc.) ; s'il désigne une configuration inter-équipes qui exige une action côté plateforme, signalez-le à l'assistance de kuploy.app. Cliquez sur Remove, puis réenregistrez après correction.
L'URL de la vitrine renvoie une erreur de certificat	Le certificat est encore en cours d'émission	Patientez une à deux minutes : Vercel émet le certificat Let's Encrypt automatiquement
L'avertissement Brevo-DNS cleanup partial: removed 0, errors 1 au Remove	Le LIST ou le DELETE des enregistrements DNS Vercel a renvoyé autre chose qu'un succès	Le centre journalise désormais la réponse réelle ([removeBrevoDnsFromVercel] LIST <zone> failed: <status> <body>). Les causes courantes : la zone parente n'est plus dans cette équipe Vercel, ou la portée du jeton d'API a changé. Les enregistrements peuvent être nettoyés à la main, depuis l'éditeur de zone de Vercel.
Le bandeau rouge « Couldn't reach the licensing hub »	Le centre est injoignable	Vérifiez l'état de kuploy.app
L'onglet Domain est absent de Settings	La combinaison de l'offre de l'organisation et de la zone gratuite coupe tout	Modifiez l'offre dans Admin → Plans, ou définissez BRANDED_EMAIL_FREE_ZONE sur l'exploitant

Ce que cela ne fait pas (encore)

• Plusieurs domaines par organisation — un seul domaine par organisation, pour cette première version.
• Le DNS automatique par l'API d'un bureau d'enregistrement — pour les domaines achetés par la plateforme. Aujourd'hui, tout domaine doit être apporté par son propriétaire.
• Le courriel entrant et les boîtes aux lettres par organisation — c'est l'affaire de l'hébergement de la messagerie, une fonctionnalité distincte, adossée à Stalwart.
• L'isolement des réputations par organisation — tout le courriel personnalisé partage la réputation d'adresse IP du compte Brevo maître.