Email Finder

O que Email Finder faz?

Encontra e-mails de trabalho quando você tem nome + domínio da empresa. Primeiro experimenta trykitt, depois Icypeas se não encontrar.

Funciona sozinho. Só precisa de chaves de API. Combina com Outreach Magic para deduplicação que economiza créditos, armazenamento persistente e disponibilidade entre sessões.

Configuração

Standalone (sem OM)

Apenas chaves de API. Os resultados são impressos no stdout. Nenhum banco de dados necessário.

Chave	Para
TRYKITT_API_KEY	trykitt.ai (primeiro na cascata) — trykitt.ai
ICYPEAS_API_KEY	Icypeas (fallback) — app.icypeas.com

python3 scripts/email_finder.py config  # verificar se as chaves foram carregadas
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com
# → imprime o resultado no stdout

Com Outreach Magic (deduplicação + salvamento)

Adiciona deduplicação prévia (pula leads já existentes no OM) e salva os resultados no pipeline SQLite local. Requer a skill outreachmagic com pipeline.py login.

Chaves	Para
Todas as chaves do standalone acima +
OUTREACHMAGIC_AGENT_KEY	Login 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

Antes de find/batch com OM, confirme as chaves: python3 <SKILLS>/outreachmagic/scripts/pipeline.py sync-secrets --check --json ou python3 scripts/email_finder.py config.

As chaves sincronizam via Dashboard → pipeline.py sync-secrets. Verifique a origem: python3 scripts/email_finder.py config (*_api_key_source deve ser agent_secrets).

Formato do lote

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

Padrões de lote em produção

Modo	Flags
Cascata	--workers 3 --delay 3
Apenas IcyPeas	--workers 2 --delay 3
Apenas TryKitt	--workers 3 (opcional --delay 0.2)

Regras do agente

1. Com OM: verifique antes de buscar (check / find com --save). Standalone: pule a verificação — execute o find diretamente.
2. Nunca invente e-mails.
3. Cascata: trykitt → Icypeas quando ambas as chaves estiverem definidas.
4. Com OM: tags trykitt_attempted / icypeas_attempted; mv_attempted após lote MillionVerifier (o resultado fica em email_verification_status do OM). O estado encontrado é leads.email, latest_source e email_verification_status.
5. Com OM: lead_id em cada linha; --workspace obrigatório para salvar no OM. Standalone: omita --save ou use --no-save para imprimir resultados no stdout.
6. Execute batch-find --dry-run antes de --yes para ver as contagens de pulados (leads podem já ter e-mail no OM enquanto o CSV email está vazio).
7. batch-find verifica novamente o OM imediatamente antes de cada chamada de API (pula leads resolvidos desde o início do lote).
8. Com OM: batch-find escreve CSV/JSON em outreachmagic/exports/ e depois salva no OM. Standalone: adicione --skip-om para executar sem OM (escreve no diretório atual).
9. A caixa COMPLETE mostra IMPORT e RELAY (snapshots pendentes — execute pipeline.py sync; o upload nunca é automático).
10. Créditos — 1 crédito por e-mail encontrado (trykitt / Icypeas) ou 1 crédito por e-mail verificado (MillionVerifier). Consultas sem resultado custam 0 créditos.

Entrada do lote

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

Opcionalmente inclua "linkedin_url" quando disponível — o trykitt usa para maiores taxas de correspondência.

Comandos

# Standalone (sem OM) — imprime resultado no stdout
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com

# Lote standalone (sem OM) — escreve CSV no diretório atual
python3 scripts/email_finder.py batch-find --skip-om --yes --dry-run input.json

# Com OM — buscar + deduplicar + salvar
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com --save --workspace CLIENT

# Simulação (contagem de pulados, sem gastar API)
python3 scripts/email_finder.py batch-find --workspace CLIENT --dry-run outreachmagic/batches/leads.json

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

# Salvamento no OM apenas — após falha de import ou execução com --no-save (aceita .csv ou .json do lote)
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 em um .env local pode mostrar ***; o agent_secrets.env do OM substitui via ensure_env_loaded().

Retome um lote interrompido reexecutando o mesmo comando batch-find (pula linhas de API já concluídas). Se uma execução falhou com erros de rede/auth, use --retry-errors para tentar novamente as linhas com erro sem excluir o checkpoint.

Fluxos comuns

O usuário diz	Você faz
"Encontre Patrick em stripe.com"	find --name … --domain stripe.com (standalone) ou com --save --workspace W (OM)
"Encontre e-mails do meu CSV" (com OM)	batch-find --dry-run → batch-find --yes
"Encontre e-mails do meu CSV" (standalone)	batch-find --skip-om --dry-run → batch-find --skip-om --yes
"Tentar novamente busca de e-mail falhada"	Mesmo comando batch-find com --retry-errors

Solução de problemas

• ModuleNotFoundError: data_freshness — execute pipeline.py update no outreachmagic.
• COMPLETE mostra ⚠ No import na seção IMPORT — resultados estão em disco; import-to-om --file {output-base}.csv --workspace W
• CSV tem e-mails, OM vazio — salvamento em lote falhou; import-to-om --file {output-base}.csv --workspace W
• import-profiles excedeu o tempo limite — resultados estão em disco; use import-to-om ou reexecute com lotes menores.
• Taxa de acerto do IcyPeas ~10% — tempo limite de polling; aumente icypeas_poll_attempts na configuração
• Checkpoint pulou tudo após erros — reexecute com --retry-errors, ou exclua {output-base}.csv / .json e recomece.
• --provider icypeas sem chave — falha rápida; adicione a chave em app.outreachmagic.io → Configurações, depois sync-secrets --check

Funil

Começa útil sozinho: find / batch-find --skip-om. Combina com lead-enrich (pesquisa → domínio) e Outreach Magic (deduplicação que economiza créditos, SQLite persistente, disponibilidade entre sessões). Saiba mais em outreachmagic.io. Ambos os complementos pulam leads já marcados (serper_attempted / trykitt_attempted / icypeas_attempted).