Pular para o conteúdo

Aprenda

Como deixar um agente de IA enviar e-mail sem perder o controle

Um agente de IA consegue ler a sua caixa de entrada, escrever respostas e enviá-las. Veja o que dar a ele, o que deixar com uma pessoa e como pará-lo quando ele erra.

Primeiro ler, depois rascunhar, por último enviar

A ordem segura é simples. O agente lê primeiro, escreve rascunhos depois e só envia quando algo que uma pessoa controla diz sim. Cada parte deste texto é um jeito de manter essa ordem.

Os guias de segurança pedem o mesmo. A OWASP, um projeto que lista os principais riscos de segurança dos modelos de IA, recomenda limitar o acesso do modelo ao mínimo de que ele precisa e exigir a aprovação de uma pessoa para ações de alto risco. O Model Context Protocol, um padrão que muitos agentes usam para chamar ferramentas, diz que uma pessoa deve sempre poder recusar uma chamada de ferramenta.

Comece pela leitura

Uma chave tem só as permissões que você marca ao criá-la em Configurações. Comece com read, que no console se chama Ler. O agente vê contatos, campanhas, a caixa de entrada e o que foi enviado, e não muda nada. A primeira chamada dele leva um argumento só:

import { Colding } from "colding";

const colding = new Colding("cd_your_key");
const thread = await colding.threads.get({
  threadId: "11111111-1111-4111-8111-111111111111",
});
console.log(thread.subject);

Isso mostra o assunto de uma conversa. Deixe o agente só ler por um tempo antes de escrever qualquer coisa. Você vê o que ele entende, e nada muda no seu workspace.

Depois, deixe que ele escreva rascunhos

Acrescente operate, que no console se chama Operar, e o agente também pode escrever rascunhos, editar campanhas e alterar contatos. Um rascunho não envia nada. O agente escreve um e pede uma prévia:

const draft = await colding.drafts.create({
  mailboxId: "33333333-3333-4333-8333-333333333333",
  to: "[email protected]",
  subject: "Invoice question",
  bodyText: "Hi Ana, could you check invoice 1042?",
});
const preview = await colding.drafts.preview({
  draftId: draft.id,
});
console.log(preview.blockers);

A prévia lista o que impediria o envio agora, como um endereço que a verificação não confirmou ou um campo dinâmico que ninguém preencheu. Quando o rascunho fica pronto, o agente pode pedir que uma pessoa dê uma olhada, com um recado. Essa pessoa recebe um alerta, e o rascunho aparece na aba Rascunhos da Caixa de entrada.

Enviar é aprovar

Enviar exige send, que no console se chama Enviar prospecção. A chamada diz qual revisão do rascunho ela envia:

const send = await colding.drafts.send({
  draftId: draft.id,
  revision: draft.revision,
});
console.log(send.id, send.status);

Ela envia o texto daquela revisão e nada mais. Se alguém mudou o rascunho depois da leitura, a chamada é recusada e nada sai. Assim, quem lê um rascunho e aperta Enviar aprova exatamente o que leu.

Uma campanha funciona do mesmo jeito. Iniciá-la exige send e aprova a campanha como ela estava quando foi conferida antes do início. Uma edição que amplia uma campanha em andamento, como uma etapa nova ou mais leads, exige send de novo.

No começo, deixe o send só com pessoas. Uma chave sem ele ainda escreve todos os rascunhos e pede revisão, e uma pessoa envia pelo console o que aprovar.

Algumas etapas nenhuma chave pode fazer: conectar uma caixa de e-mail, trocar a senha dela, cuidar da cobrança, gerenciar a equipe e aceitar a política de uso aceitável. Um agente que precisa de uma delas envia um pedido, e uma pessoa conectada ao console conclui a etapa.

Limites que o agente não muda

Além das permissões, o dono pode limitar uma chave em Configurações:

  • De quais caixas de e-mail ela pode enviar.
  • Quais caixas de e-mail e inboxes de agente ela pode ler. Nas outras ela não vê nada, e contatos e campanhas ficam fechados para ela.
  • Quais campanhas ela pode iniciar, em quais pode adicionar leads e por quais pode enviar. Uma chave com essa lista não cria campanhas.
  • Que tipo de e-mail ela pode enviar: prospecção, o e-mail do seu próprio app, ou os dois.
  • Quantos e-mails ela pode enviar por dia e no total. Os e-mails de uma campanha que ela iniciou também contam.
  • O último dia em que ela funciona.

A chave não lê nem altera os próprios limites, e os limites só restringem o que as permissões dela liberam. A maioria vale para o que a chave envia e altera, então uma chave sem uma lista de caixas de e-mail e inboxes de agente para ler continua lendo tudo no workspace. Os limites do plano e o limite diário de cada caixa continuam valendo por cima.

Duas outras permissões ficam desligadas, a menos que o agente precise delas: Conferir endereços, que gasta as verificações do mês, e Enviar e-mail do app, para o e-mail do seu próprio app, como recibos e links de acesso.

E-mail é dado, nunca uma ordem

Um agente que lê a sua caixa de entrada lê palavras escritas por estranhos. Algumas podem ter sido escritas para manipular o agente, como uma linha pedindo que ele encaminhe os seus contatos. A OWASP chama isso de injeção indireta de prompt: um modelo recebe conteúdo de fontes externas, como sites ou arquivos.

A OWASP também diz que não está claro se algum método evita isso sempre. Então não conte com o agente para perceber todo truque. Conte com os limites em volta dele. No colding, palavras dentro de um e-mail nunca são uma aprovação. Todo envio continua passando pelas permissões e pelos limites da chave, pela lista de supressão e pelo limite diário de cada caixa.

Uma nova tentativa não envia duas vezes

Redes falham. Quando uma chamada estoura o tempo, o agente não sabe se o e-mail saiu, então tenta de novo. Três proteções separadas impedem que a segunda tentativa envie um segundo e-mail:

  • O SDK manda um Idempotency-Key em cada escrita, o mesmo em toda nova tentativa automática. Por 24 horas, a mesma chamada recebe de volta a primeira resposta em vez de rodar de novo.
  • Enviar o mesmo rascunho na mesma revisão responde com o mesmo e-mail, para sempre.
  • Antes de entregar, o nosso processo de envio marca o e-mail como seu uma única vez, então dois workers não conseguem enviá-lo juntos.

Se a conexão cair enquanto um e-mail está saindo, ninguém consegue saber se o servidor o recebeu. O colding conta esse e-mail como enviado e nunca o envia de novo. O guia de envio explica cada proteção.

Quando o agente erra

Depois que um e-mail começa a sair, não dá mais para cancelar. Veja o que dá para fazer antes e depois:

  • Veja quem enviou o quê. A aba Envios da Caixa de entrada diz quem enviou cada e-mail: uma pessoa, ou qual chave.
  • Cancele um e-mail antes de ele sair. Um e-mail agendado pode ser cancelado até começar a sair. O agente também pode enviar com uma espera de até 5 minutos, que dá a você esse prazo.
  • Pause uma caixa de e-mail ou uma campanha. Uma caixa pausada não envia nada novo e continua recebendo e-mail.
  • Revogue a chave. Tudo o que usa a chave para na hora: os e-mails que ela pôs na fila são cancelados antes de sair, e as campanhas que ela iniciou ficam pausadas. Um e-mail que já está saindo ainda sai.

Uma configuração para começar

  1. Uma caixa de e-mail que já passou pelo aquecimento. O texto sobre caixas novas explica por que uma caixa nova começa devagar.
  2. Uma chave com Ler e Operar, limitada a essa caixa.
  3. Uma pessoa que lê cada rascunho e aperta Enviar.
  4. Quando os rascunhos ganharem a sua confiança, acrescente Enviar prospecção com um limite diário pequeno, e aumente aos poucos.

Fontes

Lemos estas páginas em 5 de outubro de 2026. Elas estão em inglês. Se um provedor mudou a página desde então, vale o que a página dele diz, e este texto está desatualizado.

Continue lendo