Des adresses e-mail professionnelles d'entreprises, chacune avec sa source, son statut de vérification et son score.
Bêta fermée. Code visible, tous droits réservés. MailFind n'est pas ouvert au public : pas de facturation, budget de vérification limité (20 crédits Hunter par mois), documents légaux non relus par un juriste. Le code est publié pour être lu, pas pour être réutilisé : ce n'est pas un logiciel libre ni open source (voir Licence).
MailFind prend un fichier CSV d'entreprises et rend, pour chacune, les adresses e-mail professionnelles qu'il a trouvées. Chaque adresse garde l'URL ou le fournisseur d'où elle vient, la méthode, la date, un statut de vérification et un score de 0 à 100 dont le détail s'affiche critère par critère. Les résultats s'exportent, ou partent en brouillon de campagne dans Campaign Mailer.
Application web : https://mailfind.vercel.app (Vercel). Pendant la bêta fermée, on y voit la page de connexion et quelques pages publiques ; le reste demande un compte.
La page de connexion. Les deux adresses affichées (contact@acme.fr, recrutement@beta.io) sont des exemples fictifs, pas des données collectées. Elles illustrent le format : la seconde porte le statut « le serveur accepte tout, impossible de conclure », que MailFind ne présente jamais comme vérifié.
- Importe un CSV (5 000 lignes et 5 Mo au plus) de noms d'entreprises, de domaines ou d'adresses de sites.
- Identifie chaque entreprise : identité légale (SIREN) via l'API publique « Recherche d'entreprises », domaine officiel via Brave Search quand il n'est pas fourni.
- Collecte sur les pages publiques du site officiel (accueil, contact, carrières, mentions légales, équipe), avec un simple
fetchet Cheerio, sans navigateur headless. Profondeur au choix : 3, 10 ou 25 pages par site. - Enrichit par Hunter quand le site n'a pas donné le type d'adresse cherché, puis propose des adresses de rôle sur un domaine qui reçoit du courrier.
- Vérifie : sept contrôles locaux, et un huitième niveau, la vérification de boîte par Hunter, uniquement sur demande.
- Exporte en CSV, XLSX, JSON, ou envoie vers Campaign Mailer par lots de 500, en campagne brouillon : seul l'utilisateur la lance.
- Expose une API publique
/v1: clés à portées (hachées), limite de débit par clé, idempotence, pagination par curseur, erreurs RFC 9457, webhooks signés, document OpenAPI 3.1.
- Pas d'accès à votre messagerie. Google ne transmet que le nom et l'adresse (portées d'identité). L'envoi se fait dans Campaign Mailer.
- Pas de connexion SMTP, pas de port 25. Aucun sondage de boîte depuis nos serveurs : la vérification de boîte passe par un fournisseur.
- Pas de contournement. Le robot suit
robots.txt, se limite à une requête par seconde et par domaine, s'annonce, ne se connecte à rien, ne décode pas une adresse masquée volontairement, ne contourne ni CAPTCHA ni limite de débit, et ne lit pas les pages rendues uniquement par JavaScript. - Pas d'adresse sans source. Un déclencheur de base de données (
emails_require_source) refuse l'insertion d'une adresse dont on ne sait pas d'où elle vient. - Pas de promesse de vérification. Une vérification est un statut (
valid,risky,accept_all,unknown,unverified,invalid), jamais une garantie.accept_all,unknownetunverifiedne sont ni présentés ni exportés comme vérifiés. - Pas de taux de couverture annoncé. Il dépend des sites et du budget de vérification, et n'a pas été mesuré (voir Chiffres de recette).
flowchart LR
U[Navigateur] --> W["Application web<br/>React 19 + Vite<br/>Vercel"]
W -- "/api et /v1" --> A["API Express 5<br/>Railway"]
A --> PG[("PostgreSQL 18<br/>Neon")]
A --> R[("Redis Cloud<br/>sessions + files BullMQ")]
A --> S[("Cloudflare R2<br/>gros exports")]
R --> K["Processus de traitement<br/>BullMQ<br/>Railway"]
K --> PG
K --> S
K -- "pages publiques" --> SITES[Sites des entreprises]
K -- "comptés, mis en cache, plafonnés" --> EXT["Fournisseurs<br/>Recherche d'entreprises, Brave, Hunter"]
A -- "lots de 500, brouillon" --> CM[Campaign Mailer]
Deux processus, un dépôt, un schéma de base. L'API répond aux requêtes ; le processus de traitement vide les files. L'application web ne parle à l'API que par ses propres chemins /api et /v1, que Vercel renvoie vers Railway : le cookie de session reste sur une seule origine. Le détail est dans docs/architecture.md.
Chaque étape est une tâche BullMQ indépendante : elle peut échouer, être rejouée et reprendre après un redémarrage sans refaire ce qui est fait.
flowchart LR
P["import.plan<br/>normaliser, dédupliquer"] --> I["company.identify<br/>SIREN, domaine officiel"]
I --> C["company.crawl<br/>pages publiques,<br/>adresses + sources"]
C --> E["company.enrich<br/>types manquants :<br/>fournisseur, rôles"]
E --> V["company.verify<br/>7 contrôles locaux,<br/>niveau 8 sur demande, score"]
| Principe | Où |
|---|---|
| Aucune adresse sans source | déclencheur emails_require_source, migration 0003 |
| Une vérification est un statut | backend/src/emails/visibility.ts, exports |
| Score de 0 à 100 décomposé : les lignes du détail totalisent toujours le score | backend/src/emails/score.ts (D-18) |
| Garde SSRF : aucune requête vers une adresse privée, après DNS et après chaque redirection | backend/src/net/ |
| Appels payants comptés, mis en cache et plafonnés : réserver, appeler, régler | backend/src/providers/credits.ts |
API /v1 contractuelle : des tests échouent quand une route et le document OpenAPI divergent |
backend/src/api/openapi/ |
| Intégration Campaign Mailer par son API versionnée, jamais par sa base | backend/src/campaign-mailer/ |
| Couche | Choix |
|---|---|
| Langage | TypeScript (strict), Node.js 24 |
| Interface | React 19, Vite, Tailwind CSS 4 (SPA) |
| API | Express 5, pino, Sentry, Passport (Google, identité seulement) |
| Traitement | BullMQ sur ioredis, Cheerio |
| Données | PostgreSQL 18 (Neon), 18 migrations réversibles, 26 tables ; Redis Cloud (files BullMQ et sessions node-redis) ; Cloudflare R2 |
| Hébergement | Vercel (web), Railway (API et processus de traitement, décrits dans .railway/railway.ts) |
| Qualité | Vitest, un parcours de bout en bout Playwright, ESLint, Prettier, husky |
Choix gelés et leur justification : docs/decisions.md.
Recette du 2 octobre 2026 sur un CSV de 100 lignes (entreprises réelles : jeunes pousses, grands groupes, associations, universités), exécutée depuis la machine de l'auteur contre une branche Neon de développement. Détail : docs/recette/phase-10-resultat.md.
| Mesure | Résultat |
|---|---|
| Entreprises traitées | 99 (deux lignes désignaient le même domaine et ont été réunies) |
| Sites explorés | 94 |
| Adresses relevées | 636, dont 0 sans source |
| Durée de bout en bout | 5 min 42 s, sans intervention |
| Statuts, sans vérification de boîte | 631 unverified, 5 risky |
Ces chiffres montrent que le pipeline va au bout et que la règle « pas d'adresse sans source » tient. Ils ne disent pas que ces adresses sont valides : aucune boîte n'a été vérifiée, faute de budget fournisseur (environ 318 crédits Hunter pour les 636 adresses, contre un plafond de 20 par mois). Le critère de couverture reste donc non mesuré.
Une recette antérieure de la collecte (Phase 3, clôturée le 29 septembre 2026) sur cinquante entreprises réelles a relevé 90 adresses, toutes retrouvées sur la page citée comme source.
- Bêta fermée. Phases 0 à 9 terminées, phase 10 (bêta) en cours. La phase 7B (vérification certifiée, annuaire partagé) est documentée, pas commencée.
- Essai déployé MailFind vers Campaign Mailer jamais réalisé. L'intégration est couverte par des tests de contrat contre une copie de l'API de Campaign Mailer, pas par un envoi réel entre les deux applications en ligne.
- Vérification de boîte limitée par le budget (20 crédits Hunter par mois) : l'essentiel des adresses reste
unverified. - Pas de revue juridique. Le registre des traitements, l'analyse d'impact et la mention d'information de docs/legal/ n'ont pas été relus par un juriste. MailFind ne prétend à aucune conformité.
- Pas de facturation.
- Pages rendues par JavaScript non lues : une entreprise peut repartir sans adresse, avec la raison enregistrée.
- Contributions externes non acceptées. Le projet est propriétaire et mené par une seule personne : les pull requests ne sont pas examinées. Un défaut de sécurité se signale selon SECURITY.md.
Environ 798 cas de test dans 94 fichiers (dont 36 de tests d'intégration contre un vrai PostgreSQL 18), plus un parcours de bout en bout Playwright (connexion, import, suivi, page Contacts, export). La couverture des lignes était de 89 % selon la roadmap à la fin de la phase 9 ; elle n'a pas été remesurée depuis. GitHub Actions est restreint sur ce compte : scripts/ci.mjs joue la CI en local, avec les mêmes étapes (voir plus bas).
- Phase 0 : Fondations et décisions gelées
- Phase 1 : Comptes et socle applicatif
- Phase 2 : Import CSV et entreprises
- Phase 3 : Identification et collecte sur les sites
- Phase 4 : Fournisseurs et adresses candidates
- Phase 5 : Vérification avancée et score
- Phase 6 : Bibliothèque, page Contacts et exports
- Phase 7 : API publique et intégration Campaign Mailer
- Phase 7B : Vérification certifiée et annuaire partagé (documentée, pas commencée)
- Phase 8 : Sécurité, conformité, quotas et coûts
- Phase 9 : Tests, observabilité et documentation
- Phase 10 : Mise en production et bêta (mise en ligne faite, bêta en cours)
| Document | Contenu |
|---|---|
| Cahier des charges (PDF) | Exigences fonctionnelles et techniques, modèle de données, sécurité, conformité, recette |
| Roadmap | Phases, lots de travail, critères de fin de phase |
| Décisions | Choix techniques gelés, fournisseurs, quotas, budget, avec leur justification |
| Architecture | Comment les pièces tiennent ensemble, et où regarder |
| Collecte et vérification | Ce que le robot lit, et ce qu'un statut veut dire |
| Guide de l'API | Portées, idempotence, pagination, webhooks |
| Guide de la bêta | Prise en main pour les testeurs |
| Procédures d'incident | Quoi faire quand quelque chose ne va pas |
| Provisionnement | Les services en face de l'application, et la mise en ligne |
| Sécurité et SECURITY.md | Ce qui est chiffré, rotation des clés, signalement d'une faille |
| Conformité | Registre des traitements, analyse d'impact, sous-traitants, mention d'information (non relus par un juriste) |
Une seule page est documentée en image : la connexion, ci-dessus. Il n'existe pas encore de capture à jour du tableau de bord, de l'import et de son suivi, de la page Contacts, du détail d'une adresse avec son score, des exports ni de la page de l'API. Elles seront ajoutées à partir de données d'exemple fictives, jamais d'adresses collectées.
mailfind/
├── frontend/ React 19 + Vite, point d'entrée src/main.tsx
├── backend/ API Express et processus BullMQ, point d'entrée src/index.ts
│ ├── src/ routes, services, pipeline, crawler, vérification
│ └── migrations/ SQL numéroté, chaque migration avec son retour arrière
├── e2e/ parcours de bout en bout Playwright
├── docs/ cahier des charges, décisions, provisionnement, sécurité
├── .railway/ l'infrastructure Railway, en TypeScript
├── vercel.json build, renvois et en-têtes de l'application web
├── ROADMAP.md le plan de référence, phase par phase
├── CLAUDE.md règles de travail dans ce dépôt
└── package.json racine des deux espaces de travail npm
Réservé à l'auteur : il faut des comptes et des clés pour les services externes, qui ne sont pas fournis.
npm install
cp backend/.env.example backend/.env # puis remplir
npm run check:services # les services répondent
npm run migrate -- up # schéma à jour
npm run verify # format, lint, types, tests, build
npm run dev:backend # API sur le port 3000
npm run dev:worker # traitement des imports, à lancer à côté de l'API
npm run dev:frontend # interface sur le port 5173
Le workflow de .github/workflows/verify.yml est écrit mais personne ne l'exécute. scripts/ci.mjs tient le rôle, avec les mêmes étapes et les mêmes services.
npm run ci tout, services compris, environ trois minutes
npm run ci -- --no-db sans les services, donc sans les tests d'intégration
npm run ci -- --keep garde les conteneurs, pour enquêter après un échec
Un hook de pre-push la lance avant que du code parte. Pour passer outre en connaissance de cause : SKIP_CI=1 git push.
Les tests d'intégration parlent à un vrai PostgreSQL 18, dont le nom de base doit contenir « test » : ils effacent son schéma avant de rejouer les migrations. npm run ci s'en occupe ; à la main :
docker run -d -e POSTGRES_USER=test -e POSTGRES_PASSWORD=test -e POSTGRES_DB=mailfind_test -p 5432:5432 postgres:18
$env:TEST_DATABASE_URL = "postgresql://test:test@localhost:5432/mailfind_test?sslmode=disable" # PowerShell
$env:TEST_REDIS_URL = "redis://localhost:6379" # facultatif
npm run test:integration
TEST_REDIS_URL active les tests de la file de politesse par domaine, qui vit dans Redis (docker run -d -p 6379:6379 redis:8). Sans lui, ces tests sont sautés, les autres tournent.
Recette de la collecte sur de vraies entreprises (liste de cinquante domaines fournie) : chaque site est exploré avec les vraies règles, puis chaque adresse relevée est recherchée à nouveau dans la page citée comme source.
npm run crawl:check -- docs/recette/phase-3-domaines.txt
| Commande | Ce qu'elle fait |
|---|---|
npm run ci |
la barrière complète : verrou, format, lint, types, tests, build, vulnérabilités, intégration |
npm run verify |
format, lint, types, tests, build. La barrière avant chaque commit |
npm run check:services |
prouve que Neon, Redis, R2 et les identifiants Google répondent |
npm run migrate -- status |
liste les migrations ; up applique, down revient d'une |
npm run rotate:encryption |
réécrit les secrets avec la clé courante, après une rotation |
Santé de l'API : GET /health. Appliquer un changement d'infrastructure Railway : railway config apply (sous Windows, poser d'abord $env:_ sur railway.exe, le SDK l'y cherche).
Ce projet est développé avec l'assistance de Claude Code (modèles Claude d'Anthropic) : une grande partie du code, des tests et de la documentation a été rédigée avec lui, et les commits concernés portent la mention Co-Authored-By. Les règles de travail données à l'assistant sont publiques dans CLAUDE.md. Les décisions de produit, les choix gelés de docs/decisions.md et la validation des phases reviennent à l'auteur. MailFind n'utilise aucun modèle d'IA dans son fonctionnement : une adresse vient d'une page, d'un fournisseur, d'une règle de déduction documentée ou d'une saisie.
Logiciel propriétaire. Copyright (c) 2026 Daniel Nagoloum Talla. Code visible, tous droits réservés. Voir LICENSE.
Le dépôt est public pour qu'on puisse lire le code, ce qui ne donne aucun droit de l'utiliser, le copier, le modifier ou le redistribuer. Ce n'est pas un logiciel libre ni open source.