# n8n-nodes-yahoo-mail

![npm version](https://badge.fury.io/js/n8n-nodes-yahoo-mail.svg)
![license](https://img.shields.io/npm/l/n8n-nodes-yahoo-mail)

**Community Node do n8n** para integração com **Yahoo Mail** usando **IMAP/SMTP**. 

Permite gerenciar emails do Yahoo Mail de forma automatizada sem necessidade de OAuth2 - apenas usando **email + senha de aplicativo**.

## 🚀 Funcionalidades

### 📥 Yahoo Mail Trigger
- **Tempo real**: Monitora emails novos a cada 10 segundos (configurável)
- **Múltiplas pastas**: Seleção dinâmica via IMAP (Inbox, Bulk, custom)
- **Apenas emails novos**: Não dispara para emails já existentes
- **Timezone UTC**: Comparações consistentes independente do fuso
- **Stop completo**: Para adequadamente quando desativado
- **Rate limit protection**: Proteção automática contra bloqueios
- **Filtros avançados**: Por data, texto, anexos, status de leitura

### 📧 Yahoo Mail Actions
- **Mensagens**:
  - ✅ Listar mensagens com filtros
  - ✅ Obter mensagem completa (headers + corpo)
  - ✅ Baixar mensagem em formato RFC822
  - ✅ Listar e baixar anexos
  - ✅ Marcar mensagens (lida, sinalizada, respondida)
  - ✅ Mover mensagens entre pastas
  - ✅ Excluir mensagens (soft/hard delete)
  - ✅ Enviar novas mensagens
  - ✅ Responder mensagens (mantém threading)
  - ✅ Encaminhar mensagens

- **Pastas**:
  - ✅ Listar pastas de email
  - ✅ Criar/excluir pastas
  - ✅ Esvaziar lixeira

## 📋 Pré-requisitos

1. **Conta Yahoo com 2FA habilitado**
2. **Senha de aplicativo gerada** (não a senha normal da conta)

### Como gerar senha de aplicativo no Yahoo:

1. Acesse [Configurações da Conta Yahoo](https://account.yahoo.com)
2. Vá em **Segurança** > **Gerar senhas de app**
3. Selecione **Outro (personalizado)**
4. Digite um nome (ex: "n8n-automation")
5. Clique em **Gerar**
6. **Copie a senha gerada** - você vai precisar dela para configurar as credenciais

## 🛠 Instalação

### Self-hosted n8n

#### Opção 1: npm global
```bash
npm install n8n-nodes-yahoo-mail --location=global
```

#### Opção 2: Pasta customizada
1. Copie a pasta do projeto para `${N8N_USER_FOLDER}/custom/`
2. Reinicie o n8n

#### Opção 3: Via interface n8n
1. Vá em **Settings** → **Community Nodes**
2. Clique em **Install**
3. Digite: `n8n-nodes-yahoo-mail`
4. Clique em **Install**

### n8n Cloud
Community nodes não são suportados no n8n Cloud. Use apenas em instalações self-hosted.

## ⚙️ Configuração

### 1. Criar Credenciais

1. No n8n, vá em **Credentials** → **Add new**
2. Procure por **"Yahoo App Password (IMAP/SMTP)"**
3. Configure:

```
Email: seu_email@yahoo.com
App Password: [senha de aplicativo gerada]
IMAP Host: imap.mail.yahoo.com (padrão)
IMAP Port: 993 (padrão)
SMTP Host: smtp.mail.yahoo.com (padrão) 
SMTP Port: 465 (padrão)
Use STARTTLS: false (padrão)
```

### 2. Testar Conexão

Clique em **"Test"** para verificar se as credenciais estão corretas.

## 📖 Exemplos de Uso

### Exemplo 1: Monitor de emails importantes

```json
{
  "nodes": [
    {
      "name": "Yahoo Mail Trigger",
      "type": "n8n-nodes-yahoo-mail.yahooMailTrigger",
      "parameters": {
        "mailboxes": ["Inbox"],
        "filters": {
          "unread": true,
          "search": "urgente OR importante"
        },
        "behavior": {
          "markAsSeen": true
        }
      }
    },
    {
      "name": "Slack Notification", 
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "message": "📧 Novo email importante de: {{$json.from[0].address}}\nAssunto: {{$json.subject}}"
      }
    }
  ]
}
```

### Exemplo 2: Backup de anexos no Google Drive

```json
{
  "nodes": [
    {
      "name": "Yahoo Mail Trigger",
      "type": "n8n-nodes-yahoo-mail.yahooMailTrigger", 
      "parameters": {
        "mailboxes": ["Inbox", "Bulk"],
        "filters": {
          "hasAttachment": true
        }
      }
    },
    {
      "name": "Get Attachments",
      "type": "n8n-nodes-yahoo-mail.yahooMail",
      "parameters": {
        "resource": "message",
        "operation": "getAttachments",
        "mailbox": "{{$json.mailbox}}",
        "uid": "{{$json.uid}}"
      }
    },
    {
      "name": "Download Each Attachment",
      "type": "n8n-nodes-yahoo-mail.yahooMail",
      "parameters": {
        "resource": "message", 
        "operation": "downloadAttachment",
        "mailbox": "{{$json.mailbox}}",
        "uid": "{{$json.uid}}",
        "partId": "{{$json.partId}}"
      }
    },
    {
      "name": "Upload to Google Drive",
      "type": "n8n-nodes-base.googleDrive",
      "parameters": {
        "operation": "upload",
        "name": "{{$json.fileName}}",
        "binaryData": true
      }
    }
  ]
}
```

### Exemplo 3: Resposta automática

```json
{
  "nodes": [
    {
      "name": "Yahoo Mail Trigger",
      "type": "n8n-nodes-yahoo-mail.yahooMailTrigger",
      "parameters": {
        "mailboxes": ["Inbox"],
        "filters": {
          "search": "cotação OR orçamento"
        }
      }
    },
    {
      "name": "Send Auto Reply",
      "type": "n8n-nodes-yahoo-mail.yahooMail", 
      "parameters": {
        "resource": "message",
        "operation": "reply",
        "uid": "{{$json.uid}}",
        "mailbox": "{{$json.mailbox}}",
        "message": "Obrigado pelo seu contato! Retornaremos em até 24 horas."
      }
    },
    {
      "name": "Move to CRM Folder",
      "type": "n8n-nodes-yahoo-mail.yahooMail",
      "parameters": {
        "resource": "message", 
        "operation": "move",
        "uid": "{{$json.uid}}",
        "mailbox": "{{$json.mailbox}}",
        "toMailbox": "CRM"
      }
    }
  ]
}
```

## 🔧 Desenvolvimento

### Setup do projeto

```bash
# Clone o repositório
git clone https://github.com/seu-usuario/n8n-nodes-yahoo-mail.git
cd n8n-nodes-yahoo-mail

# Instale dependências
npm install

# Build
npm run build

# Lint
npm run lint

# Format
npm run format
```

### Estrutura do projeto

```
n8n-nodes-yahoo-mail/
├── credentials/
│   └── YahooAppPasswordApi.credentials.ts
├── nodes/
│   ├── YahooMail.node.ts
│   └── YahooMailTrigger.node.ts  
├── utils/
│   ├── imap.ts
│   ├── smtp.ts
│   └── normalize.ts
├── dist/              # Build output
├── package.json
├── tsconfig.json
└── README.md
```

### Stack tecnológica

- **Node.js 20+** + **TypeScript**
- **imapflow**: Cliente IMAP moderno
- **nodemailer**: Envio de emails via SMTP
- **n8n-workflow**: Tipos e interfaces do n8n

## 🔒 Segurança

- ✅ **Zero OAuth2**: Sem tokens complexos de gerenciar
- ✅ **Senhas de app**: Mais seguro que senha principal
- ✅ **Conexões TLS**: Todas as conexões são criptografadas
- ✅ **Sem logs de senha**: Credenciais nunca são logadas
- ✅ **Timeout de conexão**: Evita conexões órfãs

## ⚠️ Limitações

- **Tamanho de anexos**: Máximo 25MB por anexo
- **Rate limiting**: Yahoo pode limitar conexões simultâneas
- **Apenas self-hosted**: Não funciona no n8n Cloud
- **2FA obrigatório**: Yahoo requer autenticação de dois fatores

## 🐛 Troubleshooting

### Erro de autenticação
```
Error: Invalid credentials
```
**Solução**: Verifique se está usando a senha de aplicativo (não a senha normal) e se o 2FA está habilitado.

### Conexão recusada
```  
Error: Connection refused
```
**Solução**: Verifique se as portas IMAP (993) e SMTP (465/587) não estão bloqueadas pelo firewall.

### Trigger não recebe emails
**Soluções**:
- Verifique se há mensagens que atendem aos filtros
- Teste com `unread: false` para ver todas as mensagens  
- Verifique se a conexão não foi interrompida (logs do n8n)

### Anexos não baixam
**Soluções**:
- Verifique se o `partId` está correto
- Confirme se a mensagem realmente tem anexos
- Teste com mensagens menores primeiro

### Trigger não para quando desativo
**Solução**: 
- Use v1.0.10+ que tem cleanup rigoroso
- Verifique logs: deve aparecer "🏁 TRIGGER COMPLETAMENTE PARADO"
- Se persistir, reinicie o n8n completamente

### Rate limit do Yahoo
**Sintomas**: "AUTHENTICATE rate limit hit", "Command failed"
**Soluções**:
- Aguarde 30-60 minutos para rate limit expirar
- Use intervalos maiores (5+ minutos)  
- Evite ativações frequentes durante desenvolvimento
- v1.0.10+ tem proteção automática

## 📄 Licença

MIT License - veja [LICENSE](LICENSE) para detalhes.

## 🤝 Contribuições

Contribuições são bem-vindas! Por favor:

1. Faça um fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

## 📞 Suporte

- 🐛 **Issues**: [GitHub Issues](https://github.com/seu-usuario/n8n-nodes-yahoo-mail/issues)
- 💬 **Discussões**: [GitHub Discussions](https://github.com/seu-usuario/n8n-nodes-yahoo-mail/discussions)
- 📖 **Documentação**: [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)

---

**Feito com ❤️ para a comunidade n8n**
