Manual de uso do conector-email

Este manual é destinado aos programadores que irão consumir o conector-email dentro do SISC.

Identificação

Objetivo

Permitir que mensagens SISC solicitem envio real de email via SMTP e busca/leitura de emails via IMAP/socket, sem que outros agentes ou conectores acessem diretamente credenciais de email.

Operações disponíveis

OperaçãoCampo acaoDescrição
Enviar emailenviarEnvia uma mensagem para o endereço informado em email.
Receber/buscar emailsreceberBusca mensagens no IMAP usando o endereço informado em email como remetente pesquisado.

Payload de entrada

CampoTipoObrigatórioDescrição
emailstringsimEndereço de destino no envio ou remetente usado na busca IMAP.
acaostringsimenviar ou receber.
mensagemstringquando acao=enviarTexto do email a enviar.
assuntostringnãoAssunto do email. Padrão: Mensagem do SISC.

Exemplo: enviar email

{
  "_protocolo": {
    "origem": "sistema__operador",
    "destino": "conector__conector-email",
    "idmensagem": "conector-email.executar"
  },
  "payload": {
    "dados": {
      "email": "destinatario@exemplo.com",
      "acao": "enviar",
      "assunto": "Assunto da mensagem",
      "mensagem": "Texto da mensagem"
    }
  }
}

Exemplo: receber/buscar emails

{
  "_protocolo": {
    "origem": "sistema__operador",
    "destino": "conector__conector-email",
    "idmensagem": "conector-email.executar"
  },
  "payload": {
    "dados": {
      "email": "remetente@exemplo.com",
      "acao": "receber"
    }
  }
}

Saída esperada

O handler escreve resultado operacional em stdout. Para receber, retorna resumo JSON contendo itens como id, from, subject, date, messageId, body e bodyPreview.

Credenciais necessárias

Nunca inclua senhas reais em pacotes ou repositórios. O operador deve criar o arquivo real apenas no servidor SISC.

Arquivo real esperado no servidor:

secretos/conector-email.json

Permissão recomendada:

chmod 600 secretos/conector-email.json

Estrutura esperada:

{
  "ativo": true,
  "smtp": {
    "ativo": true,
    "host": "smtp.gmail.com",
    "porta": 587,
    "criptografia": "tls",
    "usuario": "conta@gmail.com",
    "senha": "APP_PASSWORD_OU_CREDENCIAL_CONFIGURADA_NO_SERVIDOR",
    "remetenteEmail": "conta@gmail.com",
    "remetenteNome": "SISC"
  },
  "recebimento": {
    "ativo": true,
    "host": "imap.gmail.com",
    "porta": 993,
    "criptografia": "ssl",
    "usuario": "conta@gmail.com",
    "senha": "APP_PASSWORD_OU_CREDENCIAL_CONFIGURADA_NO_SERVIDOR",
    "caixa": "INBOX",
    "limiteMensagens": 10
  }
}

No Gmail, normalmente o operador deve usar App Password em conta com 2FA ou OAuth2, conforme a política vigente do Google e a implementação instalada. Não use a senha comum da conta se o provedor não permitir.

Erros comuns

ErroCausa provávelAção
campo obrigatorio ausente: emailPayload sem email.Enviar email válido em payload.dados.email.
acao invalidaacao diferente de enviar ou receber.Corrigir operação.
campo mensagem e obrigatorioEnvio sem texto.Informar mensagem quando acao=enviar.
configuracao nao encontradaArquivo secretos/conector-email.json ausente.Operador deve criar arquivo real no servidor.
SMTP falhou ou IMAP falhouCredenciais, host, porta, TLS/SSL ou provedor recusando conexão.Revisar configuração e política do provedor.

Boas práticas para consumidores