outreachmagic/email-finder

Email Finder

Trouvez des emails professionnels lorsque vous disposez du nom + domaine de l'entreprise. trykitt d'abord, Icypeas en cas d'échec.

Fonctionne seul. Nécessite uniquement des clés API. S'associe à Outreach Magic pour la déduplication qui économise les crédits, le stockage persistant et la disponibilité entre sessions.

Configuration

Seul (sans OM)

Juste les clés API. Les résultats s'affichent dans la sortie standard. Aucune base de données nécessaire.

Clé	Pour
TRYKITT_API_KEY	trykitt.ai (premier dans la cascade) — trykitt.ai
ICYPEAS_API_KEY	Icypeas (solution de repli) — app.icypeas.com

python3 scripts/email_finder.py config  # vérifier que les clés sont chargées
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com
# → affiche le résultat dans la sortie standard

Avec Outreach Magic (déduplication + sauvegarde)

Ajoute une déduplication préalable (ignore les leads déjà dans OM) et sauvegarde les résultats dans votre pipeline SQLite local. Nécessite la compétence outreachmagic skill avec pipeline.py login.

Clés	Pour
Toutes les clés autonomes ci-dessus +
OUTREACHMAGIC_AGENT_KEY	Connexion OM via pipeline.py login

python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com --save --workspace CLIENT
python3 scripts/email_finder.py batch-find --workspace CLIENT --yes --workers 3 --delay 3 input.json

Avant find/batch avec OM, confirmez les clés : python3 <SKILLS>/outreachmagic/scripts/pipeline.py sync-secrets --check --json ou python3 scripts/email_finder.py config.

Les clés se synchronisent via le Tableau de bord → pipeline.py sync-secrets. Vérifiez la source : python3 scripts/email_finder.py config (*_api_key_source doit être agent_secrets).

Format du lot

[{"lead_id": 12345, "name": "Jane Doe", "company_domain": "acme.com"}]

Paramètres par défaut pour les lots en production

Mode	Drapeaux
Cascade	--workers 3 --delay 3
IcyPeas seulement	--workers 2 --delay 3
TryKitt seulement	--workers 3 (--delay 0.2 facultatif)

Règles de l'agent

1. Avec OM : vérifier avant find (check / find avec --save). Seul : ignorer la vérification — exécuter find directement.
2. Ne jamais inventer d'emails.
3. Cascade : trykitt → Icypeas lorsque les deux clés sont définies.
4. Avec OM : tags trykitt_attempted / icypeas_attempted ; mv_attempted après le lot MillionVerifier (le résultat se trouve dans email_verification_status d'OM). L'état trouvé est leads.email, latest_source et email_verification_status.
5. Avec OM : lead_id sur chaque ligne ; --workspace requis pour la sauvegarde OM. Seul : omettre --save ou utiliser --no-save pour afficher les résultats dans la sortie standard.
6. Exécutez batch-find --dry-run avant --yes pour voir les compteurs d'ignorés (les leads peuvent déjà avoir un email dans OM alors que l'email CSV est vide).
7. batch-find revérifie OM immédiatement avant chaque appel API (ignore les leads résolus depuis le début du lot).
8. Avec OM : batch-find écrit CSV/JSON sous outreachmagic/exports/, puis sauvegarde dans OM. Seul : ajoutez --skip-om pour exécuter sans OM (écrit dans le répertoire courant).
9. La boîte COMPLETE affiche IMPORT et RELAY (instantanés en attente — exécutez pipeline.py sync ; le téléversement n'est jamais automatique).
10. Crédits — 1 crédit par email trouvé (trykitt / Icypeas) ou 1 crédit par email vérifié (MillionVerifier). Les recherches sans résultat coûtent 0 crédit.

Entrée du lot

[{"lead_id": 12345, "name": "Jane Doe", "company_domain": "acme.com"}]

Inclure éventuellement "linkedin_url" lorsqu'il est disponible — trykitt l'utilise pour améliorer le taux de correspondance.

Commandes

# Seul (sans OM) — affiche le résultat dans la sortie standard
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com

# Lot seul (sans OM) — écrit un CSV dans le répertoire courant
python3 scripts/email_finder.py batch-find --skip-om --yes --dry-run input.json

# Avec OM — find + déduplication + sauvegarde
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com --save --workspace CLIENT

# Essai à blanc (compteurs d'ignorés, pas de dépense API)
python3 scripts/email_finder.py batch-find --workspace CLIENT --dry-run outreachmagic/batches/leads.json

# Lot (find + sauvegarde OM)
python3 scripts/email_finder.py batch-find --workspace CLIENT --yes \
  --output-base outreachmagic/exports/emails --workers 3 --delay 3 outreachmagic/batches/leads.json

# Sauvegarde OM uniquement — après un import échoué ou une exécution --no-save (accepte un lot .csv ou .json)
python3 scripts/email_finder.py import-to-om --file outreachmagic/exports/emails.csv --workspace CLIENT

python3 scripts/email_finder.py update --check

# MillionVerifier (facultatif)
python3 scripts/email_finder.py config
python3 scripts/email_finder.py verify-credits
python3 scripts/email_finder.py verify-bulk --workspace CLIENT --dry-run
python3 scripts/email_finder.py verify-bulk --workspace CLIENT --poll --yes

MILLIONVERIFIER_API_KEY dans un .env local peut afficher *** ; agent_secrets.env d'OM prend le dessus via ensure_env_loaded().

Reprenez un lot planté en réexécutant la même commande batch-find (ignore les lignes API déjà complétées). Si une exécution a échoué avec des erreurs réseau/d'authentification, utilisez --retry-errors pour réessayer les lignes en erreur sans supprimer le point de contrôle.

Flux de travail courants

L'utilisateur dit	Vous faites
"Trouve Patrick chez stripe.com"	find --name … --domain stripe.com (seul) ou avec --save --workspace W (OM)
"Trouve les emails de mon CSV" (avec OM)	batch-find --dry-run → batch-find --yes
"Trouve les emails de mon CSV" (seul)	batch-find --skip-om --dry-run → batch-find --skip-om --yes
"Réessaie la recherche d'email échouée"	Même commande batch-find avec --retry-errors

Dépannage

• ModuleNotFoundError: data_freshness — exécutez pipeline.py update sur outreachmagic.
• COMPLETE affiche ⚠ No import dans la section IMPORT — les résultats sont sur le disque ; import-to-om --file {output-base}.csv --workspace W
• Le CSV contient des emails, OM vide — la sauvegarde du lot a échoué ; import-to-om --file {output-base}.csv --workspace W
• import-profiles a expiré — les résultats sont sur le disque ; utilisez import-to-om ou réexécutez avec des lots plus petits.
• Taux de réussite IcyPeas ~10% — délai d'attente de sondage expiré ; augmentez icypeas_poll_attempts dans la configuration
• Le point de contrôle a tout ignoré après des erreurs — réexécutez avec --retry-errors, ou supprimez {output-base}.csv / .json et recommencez.
• --provider icypeas sans clé — échoue rapidement ; ajoutez la clé sur app.outreachmagic.io → Paramètres, puis sync-secrets --check

Entonnoir

Commence par être utile seul : find / batch-find --skip-om. S'associe à lead-enrich (recherche → domaine) et Outreach Magic (déduplication qui économise les crédits, SQLite persistant, disponibilité entre sessions). Apprenez-en plus sur outreachmagic.io. Les deux compagnons ignorent les leads déjà tagués (serper_attempted / trykitt_attempted / icypeas_attempted).