outreachmagic/email-finder

Email Finder

Encuentra correos electrónicos laborales cuando tienes nombre + dominio de empresa. Primero trykitt, y Icypeas si falla.

Funciona de forma independiente. Solo necesita claves API. Se combina con Outreach Magic para ahorrar créditos mediante deduplicación, almacenamiento persistente y disponibilidad entre sesiones.

Configuración

Independiente (sin OM)

Solo claves API. Los resultados se imprimen en stdout. No requiere base de datos.

Clave	Para
TRYKITT_API_KEY	trykitt.ai (primero en la cascada) — trykitt.ai
ICYPEAS_API_KEY	Icypeas (respaldo) — app.icypeas.com

python3 scripts/email_finder.py config  # verificar que las claves se cargaron
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com
# → imprime el resultado en stdout

Con Outreach Magic (deduplicación + guardado)

Añade deduplicación previa (omite leads que ya están en OM) y guarda los resultados en tu pipeline SQLite local. Requiere la skill outreachmagic con pipeline.py login.

Claves	Para
Todas las claves independientes anteriores +
OUTREACHMAGIC_AGENT_KEY	Inicio de sesión en OM mediante 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

Antes de find/batch con OM, confirma las claves: python3 <SKILLS>/outreachmagic/scripts/pipeline.py sync-secrets --check --json ó python3 scripts/email_finder.py config.

Las claves se sincronizan mediante Dashboard → pipeline.py sync-secrets. Verifica el origen: python3 scripts/email_finder.py config (*_api_key_source debe ser agent_secrets).

Formato del lote

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

Valores por defecto para lotes en producción

Modo	Banderas
Cascada	--workers 3 --delay 3
Solo IcyPeas	--workers 2 --delay 3
Solo TryKitt	--workers 3 (opcional --delay 0.2)

Reglas del agente

1. Con OM: verificar antes de find (check / find con --save). Independiente: omitir verificación — ejecutar find directamente.
2. Nunca inventar correos electrónicos.
3. Cascada: trykitt → Icypeas cuando ambas claves están configuradas.
4. Con OM: tags trykitt_attempted / icypeas_attempted; mv_attempted después del lote de MillionVerifier (el resultado reside en OM email_verification_status). El estado encontrado es leads.email, latest_source y email_verification_status.
5. Con OM: lead_id en cada fila; --workspace requerido para guardar en OM. Independiente: omitir --save o usar --no-save para imprimir resultados en stdout.
6. Ejecutar batch-find --dry-run antes de --yes para ver los recuentos de omisiones (los leads pueden tener correo en OM mientras que el email del CSV está vacío).
7. batch-find vuelve a verificar OM inmediatamente antes de cada llamada a la API (omite leads resueltos desde el inicio del lote).
8. Con OM: batch-find escribe CSV/JSON en outreachmagic/exports/ y luego guarda en OM. Independiente: añadir --skip-om para ejecutar sin OM (escribe en el directorio actual).
9. El cuadro COMPLETE muestra IMPORT y RELAY (instantáneas pendientes — ejecutar pipeline.py sync; la subida nunca es automática).
10. Créditos — 1 crédito por cada correo encontrado (trykitt / Icypeas) o 1 crédito por cada correo verificado (MillionVerifier). Las búsquedas sin resultado cuestan 0 créditos.

Entrada del lote

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

Opcionalmente incluir "linkedin_url" cuando esté disponible — trykitt lo utiliza para obtener mejores tasas de coincidencia.

Comandos

# Independiente (sin OM) — imprime el resultado en stdout
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com

# Lote independiente (sin OM) — escribe CSV en el directorio actual
python3 scripts/email_finder.py batch-find --skip-om --yes --dry-run input.json

# Con OM — find + deduplicación + guardado
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com --save --workspace CLIENT

# Ejecución de prueba (recuentos de omisiones, sin gasto de API)
python3 scripts/email_finder.py batch-find --workspace CLIENT --dry-run outreachmagic/batches/leads.json

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

# Solo guardado en OM — después de una importación fallida o ejecución con --no-save (acepta lote .csv o .json)
python3 scripts/email_finder.py import-to-om --file outreachmagic/exports/emails.csv --workspace CLIENT

python3 scripts/email_finder.py update --check

# MillionVerifier (opcional)
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 en un .env local puede mostrarse como ***; OM agent_secrets.env lo sobrescribe mediante ensure_env_loaded().

Reanudar un lote bloqueado ejecutando de nuevo el mismo comando batch-find (omite las filas de API completadas). Si una ejecución falló con errores de red/auth, usa --retry-errors para reintentar las filas con error sin eliminar el punto de control.

Flujos de trabajo comunes

El usuario dice	Tú haces
"Encuentra a Patrick en stripe.com"	find --name … --domain stripe.com (independiente) o con --save --workspace W (OM)
"Encuentra correos para mi CSV" (con OM)	batch-find --dry-run → batch-find --yes
"Encuentra correos para mi CSV" (independiente)	batch-find --skip-om --dry-run → batch-find --skip-om --yes
"Reintentar búsqueda de correo fallida"	Mismo comando batch-find con --retry-errors

Solución de problemas

• ModuleNotFoundError: data_freshness — ejecutar pipeline.py update en outreachmagic.
• COMPLETE muestra ⚠ No import en la sección IMPORT — los resultados están en disco; import-to-om --file {output-base}.csv --workspace W
• CSV tiene correos, OM vacío — falló el guardado del lote; import-to-om --file {output-base}.csv --workspace W
• import-profiles agotó el tiempo de espera — los resultados están en disco; usar import-to-om o reejecutar con lotes más pequeños.
• IcyPeas ~10% de tasa de aciertos — tiempo de espera de encuesta; aumentar icypeas_poll_attempts en la configuración
• El punto de control omitió todo después de errores — reejecutar con --retry-errors, o eliminar {output-base}.csv / .json y empezar de nuevo.
• --provider icypeas sin clave — falla rápidamente; añadir clave en app.outreachmagic.io → Configuración, luego sync-secrets --check

Embudo

Comienza siendo útil por sí solo: find / batch-find --skip-om. Se combina con lead-enrich (investigación → dominio) y Outreach Magic (deduplicación que ahorra créditos, SQLite persistente, disponibilidad entre sesiones). Obtén más información en outreachmagic.io. Ambos acompañantes omiten leads ya etiquetados (serper_attempted / trykitt_attempted / icypeas_attempted).