IMAP
Objetivo
O conector IMAP (Internet Message Access Protocol) tem como objetivo permitir a integração da plataforma com servidores de correio eletrônico para a leitura e gestão de mensagens recebidas.
Principais cenários de uso:
- Monitoramento de caixa de entrada: Verificação constante para processamento automático de e-mails recebidos.
- Integração com sistemas legados: Captura de notificações ou alertas enviados por sistemas que se comunicam apenas via e-mail.
- Extração e automação de dados: Coleta de informações contidas no corpo das mensagens para alimentar fluxos de trabalho.
- Gestão de documentos: Processamento e armazenamento automático de anexos recebidos.
Configuração da Conexão
Como configurar no painel da Fluid
- Acesse Conexões > Nova conexão > IMAP.
- Preencha os campos de conexão:
- Host: Nome do host ou IP do servidor IMAP.
- Porta: Porta do servidor IMAP (padrão: 993).
- Nome de usuário: Usuário da conta IMAP.
- Senha: Senha da conta IMAP.
- Modo de criptografia: SSL/TLS ou STARTTLS. Padrão: SSL/TLS.
- Ignorar erros de SSL: Ignora erros de certificado SSL. Padrão: false.
- (Opcional) Configurações avançadas e Proxy: configure apenas se sua rede exigir.
- Clique em Salvar conexão e utilize o botão Testar para validar o acesso.
Requisitos (Criando conexão)
A conexão define os parâmetros técnicos para que a Fluid estabeleça comunicação com o seu servidor IMAP.
Campos da conexão
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Host | string | Sim | Nome do host ou IP do servidor IMAP. |
Porta | string | Sim | Porta do servidor IMAP. Padrão: 993. |
Nome de usuário | string | Sim | Usuário da conta IMAP. |
Senha | string | Sim | Senha da conta IMAP. |
Modo de criptografia | string | Sim | SSL/TLS ou STARTTLS. Padrão: SSL/TLS. |
Ignorar erros de SSL | boolean | Não | Ignora erros de certificado SSL. Padrão: false. |
Observações de Segurança
- Utilize conexões criptografadas (SSL/TLS) sempre que possível para proteger os dados em trânsito.
- Monitore o acesso ao servidor IMAP para detectar atividades suspeitas ou não autorizadas.
- Mantenha o servidor IMAP atualizado com os patches de segurança mais recentes.
- Implemente políticas de backup regulares para garantir a recuperação dos dados em caso de perda.
Configurando um Fluxo
Recurso: E-mail
Operação: Buscar E-mail
Permite recuperar um e-mail específico de uma mailbox. A busca utiliza o UID (Unique Identifier), garantindo precisão absoluta na recuperação da mensagem, sem riscos de capturar o item errado em caso de assuntos duplicados.
Campos da operação
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Mailbox | string | Sim | Pasta onde o e-mail está localizado (ex: INBOX). |
E-mail UID | integer | Sim | Identificador único do e-mail dentro da mailbox. |
Alterar Status | string | Sim | Define como o e-mail será marcado no servidor (PEEK, SEEN ou UNSEEN). |
Incluir anexos | boolean | Não | Indica se os anexos devem ser baixados para o diretório da engine. |
Status do E-mail (Flags)
Define como o e-mail será tratado no servidor após a leitura:
- PEEK: Apenas visualiza o conteúdo (não altera o status atual.
- SEEN: Marca o e-mail como Lido.
- UNSEEN: Mantém ou marca o e-mail como Não Lido.
Nota sobre Anexos e Latência
Ao habilitar Incluir anexos, os arquivos são salvos no diretório da engine. A resposta retornará os metadados e o caminho (path) de referência do arquivo. Atenção: O download de arquivos volumosos pode aumentar significativamente a latência (tempo de resposta) da operação.
Operação: Buscar E-mails
Permite a recuperação de várias mensagens simultaneamente através de filtros flexíveis.
Campos principais
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Mailbox | string | Sim | Pasta de origem (ex: INBOX). |
Critérios de busca | object | Sim | Filtros específicos (Remetente, Assunto, Datas, etc). |
Alterar Status | string | Sim | Define o status do e-mail no servidor após a busca. |
Limite | integer | Sim | Máximo de e-mails processados (Padrão e Máximo: 100). |
Incluir anexos | boolean | Não | Indica se deve baixar os anexos. |
Subcampos dos critérios de busca
Subcampo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Filtrar por status | array | Não | Filtra por e-mails SEEN, UNSEEN ou DELETED. |
De (From) | string | Não | Filtra pelo endereço do remetente. |
Para (To) | string | Não | Filtra pelo endereço do destinatário. |
Assunto | string | Não | Busca termos específicos no assunto. |
Desde (Since) | date | Não | E-mails recebidos a partir desta data (YYYY-MM-DD). |
Antes de (Before) | date | Não | E-mails recebidos antes desta data (YYYY-MM-DD). |
Ordem | string | Sim | Ordenação dos resultados: ASC (antigos) ou DESC (novos). |
Status do E-mail (Flags)
Define como o e-mail será tratado no servidor após a leitura:
- PEEK: Apenas visualiza o conteúdo (não altera o status atual.
- SEEN: Marca o e-mail como Lido.
- UNSEEN: Mantém ou marca o e-mail como Não Lido.
Nota sobre Anexos e Latência
Ao habilitar Incluir anexos, os arquivos são salvos no diretório da engine. A resposta retornará os metadados e o caminho (path) de referência do arquivo. Atenção: O download de arquivos volumosos pode aumentar significativamente a latência (tempo de resposta) da operação.
Operação: Excluir E-mail
Remove um e-mail específico utilizando seu UID.
Campos da operação
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Mailbox | string | Sim | Pasta onde o e-mail está localizado. |
E-mail UID | integer | Sim | Identificador único da mensagem. |
Remover permanentemente | boolean | Não | Se ativado, apaga definitivamente (expunge). |
Remoção Permanente vs. Exclusão Simples
- Ativado (True): O e-mail é apagado imediatamente. Não há possibilidade de recuperação.
- Desativado (False): O e-mail é marcado para exclusão. Ele deixará de aparecer na lista principal, mas continuará ocupando espaço até que uma limpeza seja executada pelo servidor.
Recurso: Mailbox
Operação: Listar Mailboxes
Retorna as pastas disponíveis no servidor, incluindo contagem de mensagens totais e não lidas.
Campos da operação
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Mailbox | string | Não | Nome da mailbox pai para listar subpastas. |
Guia de Listagem de Pastas
- Nível principal: Deixe o campo vazio para listar as pastas raiz (INBOX, Sent, etc).
Subpastas: Informe o caminho completo da pasta pai (ex: INBOX/Financeiro).
Na pratica
Listar Mailboxes
- Listar mailboxes principais
- Listar subpastas
Buscar E-mail
- Buscar e-mail utilizando flag PEEK (sem alterar status)
- Buscar e-mail utilizando flag SEEN (marcar como lido) \
- Buscar e-mail utilizando flag UNSEEN (manter ou marcar como não lido)
- Buscar e-mail incluindo anexos (atenção à latência)
Buscar multiplos e-mails
- Buscar e-mails filtrando por remetente e assunto
- Buscar e-mails filtrando por data e status
- Buscar e-mails incluindo anexos (atenção à latência)
Excluir E-mail
- Excluir e-mail sem remoção permanente
- Excluir e-mail com remoção permanente
Observações Finais
- O conector IMAP é ideal para leitura e processamento. Para envio, utilize o conector SMTP.
- Sempre teste as operações em ambientes controlados para evitar a perda acidental de mensagens.
- Considere as políticas de retenção do seu servidor de e-mail para evitar problemas de armazenamento.
Conclusão
O conector IMAP oferece a flexibilidade necessária para transformar sua caixa de entrada em uma fonte de dados automatizada, permitindo que sua aplicação reaja a novos e-mails de forma inteligente e organizada.