Solução de problemas do canal de e-mail
Por onde começar
- As falhas de entrada raramente produzem uma resposta visível para o usuário, porque o canal de entrada nunca responde automaticamente. Elas aparecem no Registro de incidentes de IA.
- As falhas de saída aparecem na conversa como um erro estruturado de ferramenta e também podem criar um registro no Registro de incidentes de IA.
- As falhas de rastreamento de respostas costumam ser silenciosas — o sintoma é que uma Ação agendada de IA nunca é ativada. Verifique o registro da Ação agendada de IA e o Registro de incidentes de IA em conjunto.
Para uma análise mais profunda de qualquer incidente, execute Depurar com IA. Para verificação de configuração, abra Pré-visualização de Execução do Agente.
E-mail de entrada — Recebimento
O recebimento de entrada falha silenciosamente por design — a plataforma nunca devolve nem responde automaticamente. Quando algo dá errado, a falha vai para o Registro de incidentes de IA. Um e-mail roteado chega ao agente com ou sem anexos, então é útil separar dois sintomas: o agente nunca é executado, ou o agente é executado mas não vê os arquivos.
Sintoma: os e-mails chegam ao endereço, mas o agente nunca é executado
O canal é executado sempre que o endereço de entrada corresponde a um registro de roteamento ativo. Se nada acontece, a causa está nessa configuração:
1. O Email Service na Configuração do Salesforce não está configurado
O e-mail de entrada não chegará à REDA AI, a menos que os Email Services do Salesforce estejam apontando para o handler da REDA AI.
O que verificar:
- Configuração › Email Services — confirme que um Email Service está ativo e usa a classe handler da REDA AI.
- Que ao menos um Email Service Address foi gerado e está ativo.
- Que Accept Attachments está definido como All (binário mais texto), se você pretende processar anexos.
2. Nenhum registro de roteamento corresponde ao endereço de entrada
O roteamento é o que ativa o canal para um endereço. Sem um registro de roteamento ativo correspondente, um e-mail somente com corpo é ignorado; um e-mail com anexos arquivados registra um incidente que aponta para a configuração de roteamento. De qualquer forma, nenhum agente é executado.
O que verificar (guia Administração da REDA AI › Operações › Roteamento de e-mail):
- Existe uma entrada de roteamento para este e-mail. Cada entrada precisa de um Rótulo, Endereço de e-mail, Agente e Ativo = ligado.
- Se você vir uma entrada acinzentada, ela está desativada — clique no ícone de marcação para reativá-la.
- A correspondência é exata — o endereço completo ou a parte antes do
@. Curingas e correspondência em nível de domínio não são suportados. - O Agente na entrada de roteamento deve ser um agente de canal API ativo. Agentes Interno, de Comunidade e de Widget externo não aparecem no seletor porque o pipeline de e-mail é executado no lado do servidor.
Sintoma: o agente é executado, mas não vê os anexos
O e-mail chegou ao agente, mas os arquivos esperados não estão na conversa. Isso é uma questão de tratamento de anexos, não do canal — o corpo do e-mail passou normalmente.
1. O processamento de anexos está desativado
Email File Processing Enabled é o controle de segurança de anexos, desativado por padrão em uma instalação nova. Com ele desativado, um e-mail roteado ainda chega ao agente como uma conversa, mas seus anexos são ignorados — nada é arquivado e nenhum incidente é registrado.
O que verificar: ative Email File Processing Enabled na guia Administração da REDA AI se você quiser que os arquivos de entrada sejam arquivados e passados ao agente.
2. Os anexos foram filtrados
Com o processamento de anexos ativado, dois filtros descartam anexos silenciosamente antes que cheguem ao agente:
- Anexos menores que o limite mínimo (~10 KB para binário, valor muito pequeno para texto) são ignorados como logotipos e imagens de assinatura.
- Anexos cuja extensão não está na Configuração de Plataforma Allowed File Extensions são descartados.
Se todo anexo for filtrado, o agente ainda é executado com base no corpo do e-mail — apenas não recebe arquivos. Isso é intencional; logotipos e imagens inline soltas não devem ser tratados como documentos.
O que verificar:
- A configuração Allowed File Extensions inclui os tipos de arquivo que o remetente está usando.
- Os tamanhos reais dos arquivos — arquivos muito pequenos serão filtrados como assinaturas mesmo que sejam documentos legítimos.
Sintoma: um anexo foi processado, mas o agente falhou
Quando o job de processamento de e-mail em segundo plano retorna um erro, a plataforma registra um incidente com o erro subjacente no corpo da mensagem, prefixado com o remetente e o assunto de entrada para contexto. O texto exato do rótulo usado é “Email file processing failed” com o título “An error occurred while processing the email attachment.”
O que verificar:
- A Conversa de IA criada para a execução — a mensagem do assistente conterá o erro estruturado.
- O registro do Registro de incidentes de IA — ele inclui o endereço De e o Assunto originais, para que você possa correlacionar a um e-mail de entrada específico.
- Execute Depurar com IA no incidente, se a mensagem de erro não for autoexplicativa.
Sintoma: nenhuma resposta automática foi enviada ao remetente
Isso é intencional. O canal de entrada nunca responde automaticamente, nunca devolve o e-mail e nunca confirma o recebimento. Se você precisar confirmar o recebimento de e-mails de entrada, configure o agente para chamar uma ferramenta de e-mail de saída ao final de sua execução.
E-mail de saída — Enviado pelo agente
As falhas de saída aparecem para o agente como erros estruturados de ferramenta, que aparecem na transcrição da Conversa de IA como o resultado da ação.
Sintoma: “Failed to send email: …”
Este é o erro literal que o agente produz quando um envio de saída falha. O texto após os dois-pontos é o erro subjacente do Salesforce.
O que verificar:
- O texto após os dois-pontos — essa é a causa real. Motivos comuns: configurações de deliverability (Email Deliverability definido como System ou No Access), limite diário de e-mail com Apex excedido, regras de validação no EmailMessage, endereço Org-Wide Email verificado ausente quando o agente espera um.
- Configuração › Email Administration › Deliverability — confirme se o nível de acesso permite que o usuário em execução envie.
- Em organizações sandbox, confirme se o Deliverability está pelo menos em System Email Only, se o agente estiver sendo testado.
Sintoma: o e-mail foi enviado, mas não está vinculado a um Contato ou Lead
O agente tenta resolver o endereço de e-mail do destinatário em relação aos registros de Contato e Lead. Quando o endereço corresponde a um único registro, o e-mail é vinculado a esse registro para o histórico de atividades. Quando o endereço corresponde a mais de um registro, ou a nenhum, o e-mail ainda é enviado, mas não é vinculado.
O que verificar:
- Se o endereço do destinatário existe como o campo Email em um único Contato ou Lead.
- A segurança em nível de campo do usuário em execução no campo Email de Contato e Lead — a busca é executada em modo de usuário, então o acesso negado faz a busca falhar silenciosamente.
- Se o agente passou o endereço de e-mail corretamente — as buscas são de correspondência exata.
Sintoma: o e-mail é enviado do endereço do usuário em execução, não do endereço da marca
A plataforma roteia por um Org-Wide Email Address apenas quando um está verificado e marcado como “Allow All Profiles”. Se não existir tal endereço, o e-mail é enviado do endereço pessoal do usuário em execução.
O que verificar:
- Configuração › Organization-Wide Addresses — que o endereço da marca está verificado.
- Que o sinalizador Allow All Profiles está ativado. Se estiver restrito a perfis específicos, a plataforma não o utilizará.
Sintoma: as assinaturas aparecem inconsistentes entre usuários
O agente anexa a assinatura configurada do Salesforce do usuário em execução, quando houver uma definida; caso contrário, monta uma assinatura de reserva a partir do nome, cargo e e-mail do usuário.
O que verificar:
- A assinatura configurada de cada usuário em suas configurações pessoais de e-mail.
- Se você prefere uma assinatura centralizada — nesse caso, construa uma ferramenta de e-mail de saída personalizada que use um Email Template, em vez da ferramenta send_email nativa.
Sintoma: lotes grandes de saída param depois de um tempo
O e-mail de saída é um Messaging.SingleEmailMessage comum do Salesforce, que conta para o limite diário de governança de e-mail com Apex. Uma vez atingido o limite, os envios seguintes falham até que o limite seja redefinido.
O que verificar: Configuração › Email Administration para monitorar o uso do dia. Para frotas de agentes de alto volume, distribua o trabalho de saída agendando ações ao longo do dia, em vez de enviar em rajadas concentradas.
Rastreamento de respostas
O rastreamento de respostas vincula uma resposta de entrada em um e-mail enviado pelo agente de volta a uma Ação agendada de IA pendente e a ativa. As falhas aqui costumam ser silenciosas — a ação simplesmente não é disparada.
Sintoma: o destinatário respondeu, mas a Ação agendada de IA nunca foi ativada
Verifique primeiro o interruptor principal e depois estas seis causas:
0. O rastreamento de respostas de e-mail está desligado — e ele já vem desligado. A configuração de plataforma Email Reply Tracking vem desabilitada por padrão. É a primeira coisa que o handler verifica em um e-mail de entrada e, quando está desligada, o handler retorna imediatamente — nenhuma das seis causas abaixo chega a ser avaliada, e nada é registrado para dizer por quê. Ative-a em REDA AI Administration › Configuration › System & Notifications antes de investigar qualquer outra coisa.
O rastreamento de respostas também exige que o Enhanced Email esteja habilitado na
organização. Sem ele, o Salesforce não cria os registros EmailMessage dos quais todo o
mecanismo depende.
1. A resposta nunca chegou ao Salesforce
O rastreamento de respostas depende de respostas de entrada que gerem registros EmailMessage no Salesforce. Se sua organização não usa Email-to-Case (ou outra configuração que capture respostas como EmailMessage), a resposta não fica visível para a plataforma e o rastreamento não pode ser acionado.
O que verificar: se a resposta de entrada criou um registro EmailMessage. Se não, a infraestrutura de e-mail subjacente não está roteando as respostas para o Salesforce.
2. O Flow acionado por registro no EmailMessage não está configurado
A plataforma não consulta registros EmailMessage por conta própria. Os clientes configuram um Flow acionado por registro no EmailMessage que chama o invocável “Process Inbound Emails”.
O que verificar:
- Configuração › Flows — que o Flow existe, está ativo e é acionado após a criação de um registro no EmailMessage.
- Sua condição de entrada inclui
Incoming = TRUE, para que EmailMessages de saída não o acionem. - Ele chama a Ação Apex “Process Inbound Emails” com o Id do registro que o acionou.
3. O e-mail de saída original não foi enviado com uma group key
O rastreamento de respostas só vincula respostas a Ações agendadas de IA quando ambas as chamadas compartilham uma group_key. Sem uma, a plataforma não tem nada para comparar.
O que verificar: o prompt/configuração do agente para confirmar que ele passa uma group_key tanto na chamada send_email quanto na chamada schedule_action rastreada por resposta. A group key é tipicamente o Id da conversa, mas qualquer string consistente funciona.
4. A Ação agendada de IA não estava em estado pendente quando a resposta chegou
O rastreamento de respostas só corresponde a ações que ainda estão pendentes. Se a ação já foi executada (talvez por uma resposta anterior ou por um fallback de tempo limite), uma resposta posterior não tem o que ativar.
O que verificar: o status do registro da Ação agendada de IA. Se ele já saiu do estado pendente, o rastreamento de respostas está funcionando — a ação simplesmente foi disparada antes do esperado.
5. Colisões de correspondência de assunto
Quando a resposta de entrada não carrega uma referência de thread pai, a plataforma recorre à correspondência de assunto (prefixos Re: e Fwd: removidos). Se duas Ações agendadas de IA pendentes compartilham um assunto normalizado idêntico, o comparador não consegue diferenciá-las e a resposta pode ativar a ação errada.
O que verificar: se os e-mails de saída no mesmo agente usam assuntos distintos. Assuntos genéricos (“Update”, “Following up”) são armadilhas para o rastreamento de respostas.
6. O usuário que executa o Flow não tem acesso aos registros de Ação agendada de IA
A consulta de correspondência é executada em modo de usuário. Se o usuário sob o qual o Flow do EmailMessage é executado — tipicamente o usuário Automated Process do Email-to-Case — não puder ver os registros de Ação agendada de IA, a correspondência não produz resultados.
O que verificar: o conjunto de permissões do usuário que executa o Flow em relação ao objeto Ação agendada de IA.
Sintoma: a resposta errada ativou a ação
Na maioria das vezes, é o caso de colisão de assunto descrito acima. Dê aos seus e-mails de saída assuntos distintos, ou dependa da vinculação de threads do Salesforce para preencher a referência pai (que o comparador prefere em vez do assunto).
Como analisar uma falha de e-mail
-
Identifique o sub-canal.
Recebimento de entrada (conversacional ou de documento), e-mail de saída enviado pelo agente, ou rastreamento de respostas. Os caminhos de diagnóstico não se sobrepõem muito.
- Para entrada: verifique o Registro de incidentes de IA em busca da mensagem relevante. As falhas de entrada raramente aparecem em outro lugar.
- Para saída: abra a transcrição da Conversa de IA e veja o resultado da ação na chamada de ferramenta relevante. A mensagem da plataforma vai citar o erro do Salesforce.
- Para rastreamento de respostas: abra o registro da Ação agendada de IA e verifique seu status. Se ainda estiver Pending, a correspondência não aconteceu; a resposta foi filtrada, não chegou, ou não correspondeu. Se estiver Executed, o sistema está funcionando — a ativação já aconteceu.
-
Execute Depurar com IA.
A análise multi-turno geralmente reduz a causa mais rápido do que ler o erro bruto. Veja Depurar com IA.
Perguntas frequentes
Se o agente nunca é executado, o endereço não está roteado: confirme se o Email Service aponta para o handler da REDA AI e se um registro de roteamento ativo corresponde ao endereço (um e-mail somente com corpo enviado a um endereço não roteado é descartado sem gerar incidente). Se o agente é executado mas os arquivos estão faltando, isso é tratamento de anexos: o Email File Processing pode estar desativado (anexos ignorados, sem incidente por design), ou os anexos foram filtrados por serem muito pequenos ou por terem uma extensão não permitida — verifique se a configuração está ativa e se os arquivos estão na lista de permissões.
No registro do Registro de incidentes de IA. A plataforma inclui o endereço De e o Assunto no corpo da mensagem do incidente ao registrar uma falha de processamento de anexo, para que você possa correlacionar o incidente a um e-mail de entrada específico.
O texto completo do erro inclui dois-pontos seguidos pelo erro subjacente do Salesforce. Se a resposta do agente o truncou, veja o resultado da ação na mensagem da Conversa de IA — o resultado estruturado da ferramenta contém o erro completo.
O comparador prefere a referência de thread pai definida pela vinculação de threads do Salesforce. Quando essa referência está presente, a correspondência é robusta. Quando não está, o comparador recorre à comparação de assuntos — que é sensível a colisões de assunto entre ações pendentes. Assuntos distintos por e-mail de saída reduzem a taxa de falhas.
O rastreamento de respostas depende de respostas de entrada que gerem registros EmailMessage no Salesforce. O Email-to-Case é a configuração mais comum que faz isso, mas qualquer configuração que crie registros EmailMessage na entrada funciona. Se sua organização não tiver essa configuração, o rastreamento de respostas não será acionado — a plataforma funciona normalmente e o recurso simplesmente não faz nada nesse caso.
Configure um Org-Wide Email Address verificado na Configuração do Salesforce com a opção Allow All Profiles ativada. A plataforma roteia por esse endereço sempre que ele estiver disponível; caso contrário, recorre ao endereço pessoal do usuário em execução.
O arquivo é muito pequeno (a plataforma filtra anexos muito pequenos para descartar logotipos e imagens de assinatura), a extensão não está na configuração Allowed File Extensions, ou o arquivo excede o Max File Size. Os três filtros são configuráveis pelo administrador.
Não. O roteamento corresponde apenas ao endereço completo ou à parte local (antes do @). Curingas e correspondência em nível de domínio não são suportados — crie um registro de roteamento por endereço.
Próximos passos
Leia Registros de incidentes de IA para a estrutura de registro subjacente, ou revisite a página de canal relevante: Canal de Email — Recebimento, Canal de e-mail — Envio, Gestão de Respostas de E-mail.