Agentes de IA

Dois tipos de agente

Um agente trabalha no Mailroomly de uma de duas formas. A escolha depende de para quem trabalha:

Ambos se ligam ao mesmo servidor MCP, com as mesmas ferramentas. Esta página trata primeiro do seu próprio agente; o agente para a organização está em Um agente para a organização.

Criar um token pessoal

Um token pessoal permite que o seu próprio agente trabalhe em seu nome: só chega aos endereços que consegue abrir e não faz nada que só um administrador faz, a menos que lhe dê as áreas de Administração, dentro do que o seu acesso permite. Dê a cada agente o seu próprio token, para os poder revogar separadamente.

1. Abra Os meus agentes: Definições › Os meus agentes › Abrir Os meus agentes, o menu da conta, ou Ctrl K › Ligar um agente de IA (os administradores escolhem depois Em seu nome).

2. Em Tokens de agentes de IA, escolha Criar token. O diálogo Criar um token pessoal abre-se.

3. Dê-lhe um Nome que reconheça mais tarde, por exemplo "Claude no meu portátil".

4. Em Acesso, deixe só o que o agente precisa:

   Acesso	O agente pode
   Listar endereços	Ver que endereços pode usar
   Ler conversas	Ler as conversas desses endereços
   Deixar rascunhos para aprovação	Deixar respostas para aprovar e passar conversas às pessoas
   Responder e escrever emails	Responder, responder a todos, reencaminhar e escrever emails novos a partir desses endereços (também pode deixar rascunhos)

   Responder e deixar rascunhos incluem ler conversas, e ambos exigem acesso Ler e responder ao endereço. Com Deixar rascunhos para aprovação e sem Responder e escrever emails, o agente nunca envia sozinho: cada resposta fica à sua espera na caixa de entrada.

5. Em Que endereços trata este agente?, escolha Todos os meus endereços (todos os endereços a que tem acesso, agora ou no futuro) ou Só os que eu escolher, por exemplo um agente de suporte que só vê o suporte@. Quando escolhe um único endereço, é sugerido um nome (Agente de suporte, Agente comercial, Agente de faturação, ou Agente de seguido do endereço) até escrever o seu.

6. Os administradores, e quem gere alguns domínios e aplicações, escolhem primeiro O que pode fazer este agente?: Apenas responder a emails (por omissão), Tudo o que posso fazer ou Apenas o que escolher, que mostra Administração (opcional) com todas as áreas por selecionar. Um agente nunca faz mais do que a pessoa: quem gere uma parte da organização entrega apenas essa parte (Deixe o seu agente administrar a organização).

7. Em Expira, escolha Daqui a 30 dias, Daqui a 90 dias (por omissão), Daqui a 365 dias ou Nunca. Um token sem expiração funciona até ser revogado.

8. Escolha Criar token.

O acesso, os endereços que o agente trata, a Administração e a expiração

Token pessoal criado mostra o token, que começa por mp_pat_, o URL do servidor MCP e a configuração para Claude Code, Cursor, JSON e cURL, já com o token preenchido. Copie o que o seu agente precisa e escolha Confirmar que guardou o token.

Importante

O token só é mostrado uma vez. O Mailroomly guarda apenas um hash e não o consegue mostrar outra vez. Se o perder, revogue-o e crie outro.

Revogar um token

Em Os meus agentes, cada token aparece com o acesso, os endereços, quando expira e quando foi usado pela última vez. Ver os pedidos mostra todos os pedidos que fez, com o resultado (Pedidos). Revogar desativa-o de imediato.

Atenção

Revogar não pode ser anulado: todos os agentes e scripts que usam o token perdem o acesso de imediato.

Um token pertence à organização em que o criou, e só funciona nela: se pertence a várias, Os meus agentes mostra os tokens da organização em que está (Mudar de organização). Também deixa de funcionar quando a sua função nessa organização muda, quando é desativado nela ou sai dela, quando a sua palavra-passe muda (o que termina todos os seus tokens) ou quando a organização desliga os tokens pessoais. Passa então a aparecer como revogado e deixa de contar. Pode ter até 20 tokens ativos em cada organização.

Quando os tokens pessoais estão desligados na sua organização, Os meus agentes avisa, Criar token não está disponível e os tokens existentes não funcionam até serem novamente ativados.

Ligar um cliente MCP

Qualquer cliente precisa de duas coisas:

Ligue-o, no topo de Os meus agentes, tem a mesma configuração pronta a colar, com um marcador no lugar do token. A configuração mostrada quando cria um token já o traz preenchido. O Claude, o ChatGPT e o Grok só precisam do URL do servidor: inicia sessão em vez de copiar um token (Claude, ChatGPT, Grok e outras plataformas de agentes).

Claude Code

Corra isto uma vez, com o seu token no lugar de mp_pat_…:

claude mcp add --transport http mailroomly https://app.mailroomly.com/mcp --header "Authorization: Bearer mp_pat_…"

Depois peça, por exemplo, "Liste os meus endereços e resuma as conversas por responder no suporte@."

Sugestão

Para o token não ficar no histórico da shell, ponha-o primeiro numa variável de ambiente e escreva --header "Authorization: Bearer $MAILROOMLY_TOKEN": a shell substitui-a quando o servidor é adicionado.

Cursor, VS Code e outros clientes

Os clientes configurados com um ficheiro JSON usam esta forma:

{
  "mcpServers": {
    "mailroomly": {
      "type": "http",
      "url": "https://app.mailroomly.com/mcp",
      "headers": { "Authorization": "Bearer mp_pat_…" }
    }
  }
}

• O Cursor lê-a de .cursor/mcp.json. Aí, um servidor remoto é o seu url e os headers, sem type. O Cursor consegue ler o token de uma variável de ambiente: "Authorization": "Bearer ${env:MAILROOMLY_TOKEN}".
• O VS Code lê .vscode/mcp.json, onde a mesma entrada fica em servers em vez de mcpServers.
• O ficheiro de projeto do Claude Code, .mcp.json, usa exatamente a forma acima e substitui ${MAILROOMLY_TOKEN}.

Um cliente que não substitui variáveis envia o texto tal como está, e o servidor responde que o token não é válido: ponha o próprio token na configuração desse cliente e mantenha o ficheiro fora do controlo de versões.

Para confirmar o token sem um cliente, liste as ferramentas que pode usar:

curl https://app.mailroomly.com/mcp \
  -H "Authorization: Bearer mp_pat_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude, ChatGPT, Grok e outras plataformas de agentes

O Claude, o ChatGPT e o Grok ligam-se com início de sessão no Mailroomly, sem token para copiar. Qualquer cliente que siga a norma do MCP para iniciar sessão também.

1. No Claude, no ChatGPT ou no Grok, adicione um conector personalizado com o URL do servidor https://app.mailroomly.com/mcp. A lista Aplicações ligadas vazia, em Os meus agentes, tem o endereço pronto a copiar.
2. Ligue-o. A plataforma abre o Mailroomly no seu browser: inicie sessão, se ainda não o fez.
3. Ligar Claude ao Mailroomly (ou o nome do seu agente) mostra para onde volta, por exemplo No fim, volta a claude.ai, e a organização em que está. Se pertence a várias, escolha aquela em que o agente trabalha.
4. Escolha o que pode fazer e que endereços trata, como num token pessoal. Os administradores veem também Administração (opcional), sem nada marcado, e as áreas que o agente pediu: dê só aquelas de que precisa (Deixar o seu agente administrar a organização).
5. Escolha Permitir. Volta à plataforma, que já pode usar os seus endereços. Cancelar leva-o de volta sem ligar nada.

Para onde volta, o que pode fazer e que endereços trata

Cuidado

Confirme o endereço por baixo do nome do agente antes de escolher Permitir: é para lá que o Mailroomly o envia de volta. Se não for a plataforma de onde partiu, escolha Cancelar.

O Mailroomly envia-lhe um email sempre que uma aplicação se liga à sua conta. Um agente ligado assim conta como um dos seus tokens: assina as respostas com o nome dele e o seu, e deixa de funcionar nos mesmos casos que um token.

Aplicações ligadas

Os meus agentes lista as plataformas que ligou em Aplicações ligadas, com o que podem fazer, os endereços, para onde o levam de volta, quando as ligou e quando foram usadas pela última vez. Ver os pedidos mostra todos os pedidos que uma fez (Pedidos). Desligar para uma de imediato; para a voltar a usar, ligue-a de novo a partir da plataforma. Os administradores veem-nas na Equipa, com os tokens de cada pessoa, marcadas como Aplicação ligada.

Um Claude ligado, com o acesso e para onde o leva de volta

O que pode pedir ao seu agente

Peça por palavras suas; o agente escolhe a ferramenta. Só vê as ferramentas que o token ou a chave permitem, e só nos seus endereços.

O que um agente envia conta para os limites diários como qualquer outro email: através de um token pessoal, o seu e o da organização; através de uma chave, o da chave e o da organização (Limites diários). As ferramentas de leitura partilham as leituras por minuto da sua organização: acima delas, o agente fica a saber quanto tempo deve esperar.

Pegar numa conversa

Um agente pega numa conversa antes de a tratar, com claim_thread, ou pega na que espera há mais tempo com claim_next_thread. A conversa passa para Com o agente com o nome do agente, os outros agentes deixam-na, e as pessoas do endereço veem que está em mãos. Uma conversa em que ninguém pegou fica em Requer a sua atenção, por isso peça ao seu agente que pegue nas conversas que trata.

O agente tem o tempo que o endereço permite (30 minutos por omissão; Quando um agente pega numa conversa) e volta a pegar nela para continuar. A resposta, um rascunho ou passar a conversa terminam-no, e release_thread devolve-a às pessoas. Quando uma pessoa responde, assume a conversa ou a atribui, o agente para; uma aplicação é avisada com um webhook conversation (Webhooks).

Rascunhos para aprovação e passar conversas

O seu agente pode optar por não enviar:

• Um rascunho para aprovação. Com draft_reply, o agente deixa a resposta por baixo da última mensagem, com o motivo por que a reteve, por exemplo Retido porque oferece um reembolso. A conversa mostra Rascunho pronto em Requer a sua atenção, e aprova-o, edita-o ou descarta-o na Caixa de entrada. Um rascunho mais recente do mesmo agente substitui o que estava pendente.
• Passar a conversa. Com hand_over_thread, o agente entrega a conversa às pessoas do endereço: passa para Requer a sua atenção com a nota do agente, e os agentes deixam de responder nela até uma pessoa a devolver. Com o email de um colega (assignee), passa-a a essa pessoa, que a encontra em Comigo (Atribuir uma conversa).

Enquanto uma pessoa tem uma conversa (depois de Eu respondo, ou de responder nela), as respostas do agente nessa conversa são recusadas: em vez disso, deixa um rascunho. Enquanto outro agente trata uma conversa, um agente pode lê-la, mas não pegar nela, responder, deixar um rascunho ou passá-la. Um agente que nunca deve enviar sozinho recebe Deixar rascunhos para aprovação sem Responder e escrever emails.

Nota

Um agente ou uma aplicação pode sempre perguntar a que acede: get_my_access responde em palavras simples, por nome, e todas as ferramentas que não pode usar já estão ocultas. Para lá disso, a recusa di-lo: OUTSIDE_YOUR_ACCESS significa que não faz parte do acesso, e um administrador pode alterá-lo na Equipa.

Deixar o seu agente administrar a organização

Como administrador, pode deixar o seu próprio agente configurar e gerir a organização por si, por exemplo durante a integração. Quem gere alguns domínios e aplicações pode fazer o mesmo com esses, e com as Campanhas se as tiver. Administração (opcional) em Criar um token pessoal mostra apenas o que pode entregar, e o agente recebe apenas o que as áreas marcadas e o seu próprio acesso permitem em conjunto. Marque só as áreas de que precisa:

Marcar qualquer uma mostra Este agente pode alterar a sua organização. O que o agente faz fica registado como feito por si, com este token. Que endereços trata este agente? limita as conversas que lê e responde, não o que administra.

Depois peça ao seu agente para "configurar a organização". Os clientes que oferecem prompts MCP mostram também Set up the organization (set_up_organization), que aceita o seu domínio, se o tiver. Guia o agente pela ordem dos Primeiros passos: o endereço gratuito ou o seu domínio e os registos DNS, os endereços (suporte@, comercial@, faturacao@), a equipa e quem pode abrir cada endereço, as aplicações e as suas chaves, e um email de teste. O prompt pede ao agente que descreva cada alteração e espere pela sua confirmação, que deixe as eliminações consigo e que não convide ninguém nem envie nada que não tenha pedido. Um agente que responde a um endereço tem o seu próprio token, que é o administrador a criar.

Todos os administradores são avisados:

• Quando cria um token com qualquer área de Administração, todos os administradores recebem o aviso Token de agente de IA que administra a organização, também por email (aviso). O token aparece com Administra a organização nas listas, para que outro administrador possa revogar um token que não reconheça, em Equipa › a pessoa › Tokens de agentes de IA.
• Quando um token destes cria uma chave de API, todos os administradores recebem Chave de API criada por um agente de IA (aviso). A chave continua a funcionar depois de o token ser revogado, até alguém a revogar.
• Quando um token destes cancela email à espera de envio, todos os administradores recebem Email em fila cancelado por um agente de IA (aviso).

Revogue o token quando o trabalho terminar.

O que fica com uma pessoa com sessão iniciada

Importante

Há coisas que nunca se fazem com um token, sejam quais forem as suas áreas, por MCP ou pela API. É uma pessoa com sessão iniciada no Mailroomly que as faz na aplicação web.

• O que não pode ser anulado: eliminar um domínio, um endereço (com as suas conversas) ou uma aplicação; revogar uma chave de API ou o token pessoal de alguém; renovar um segredo de webhook; em Campanhas, eliminar uma lista, um modelo, um formulário de inscrição, uma automação ou uma imagem alojada, e retirar um dos seus campos de todos os contactos.
• Direitos de administrador: convidar um administrador, tornar um membro administrador e mudar a função ou o estado de um administrador (o que também termina os tokens desse administrador). Um token convida membros e desativa ou reativa membros.
• Email: uma chave de API que lê email ou responde a endereços (uma chave criada por um token só pode enviar e ler ou gerir endereços bloqueados); enviar o email de um endereço para uma aplicação ou um webhook, o que inclui definir a aplicação responsável ou o URL do webhook de receção de um endereço, e alterar o webhook de uma aplicação que tem endereços ou já recebeu o email deles.
• O que uma chave alcança: alterar os domínios e endereços de uma chave existente (a que emails acede uma chave).
• Avisos sobre agentes e chaves: fechar Token de agente de IA que administra a organização, Chave de API criada por um agente de IA e Chave de API com acesso a mais endereços.
• A conta de envio própria da sua organização: adicionar lá um domínio (contas próprias).
• Tudo o resto que pertence a uma pessoa: criar e revogar tokens pessoais, apagar os dados de uma pessoa, aceitar os termos de serviço, e exportar ou encerrar a organização.

Quando o agente pede uma destas, recebe uma recusa que a identifica (em inglês, a língua dos agentes), por exemplo:

SIGNED_IN_ONLY: Deleting a domain needs a person signed in to Mailroomly: ask them to do it in the web app (https://app.mailroomly.com/docs/en/ai-agents#signed-in-only)

O agente diz-lhe então o que fazer na aplicação web.

O seu cliente pergunta antes de alterar

Cada ferramenta diz ao seu cliente que tipo de ação é: uma que só lê, uma que adiciona ou altera algo, uma que retira algo que pode ser reposto, ou uma que envia email. Os clientes usam isto para lhe perguntar antes de agir, para que confirme cada alteração e cada envio enquanto as leituras correm sozinhas. Como e quando um cliente pergunta é uma definição dele: mantenha as confirmações ligadas para tudo o que altera ou envia.

Quando o agente cria uma chave de API, ou lê o segredo de webhook de uma aplicação, o segredo chega uma vez, com a instrução de lho entregar e não o repetir. Guarde-o onde deve ficar e não o cole em conversas.

Um agente para a organização

Um agente que trabalha para toda a organização, e não em nome de uma pessoa, é uma aplicação com chave própria. Não age em nome de ninguém em particular, e as respostas aparecem assinadas com o nome da aplicação. São os administradores que o ligam:

1. Abra Aplicações › Ligar um agente de IA (ou Ctrl K › Ligar um agente de IA) e escolha Para a organização.
2. Dê-lhe um Nome da aplicação, por exemplo "Agente de suporte".
3. Em Como responde, escolha:
   • Responde sozinho: responde às conversas e deixa um rascunho quando quer que uma pessoa confirme. Pode intervir a qualquer momento.
   • Apenas rascunhos para aprovação: cada resposta é um rascunho para uma pessoa enviar, editar ou descartar. Nunca envia sozinho.
4. Em A que emails acede esta chave?, indique o que precisa. Para manter um agente em suporte@, escolha Só estes endereços (a que emails acede uma chave).
5. Escolha Criar a aplicação e a chave.

Para quem trabalha o agente: a organização ou você

A chave, que começa por mp_live_, é mostrada uma vez em Chave de API (para enviar): copie-a para a configuração ou o cofre de segredos do agente. Ligue-a ao seu agente tem a configuração para Claude Code, Cursor, JSON e cURL. Leem a chave da variável de ambiente MAILROOMLY_API_KEY, para que o código nunca a contenha; num cliente que não lê variáveis de ambiente, ponha a chave no lugar da variável. O URL do servidor e o cabeçalho são os mesmos de um token pessoal: Ligar um cliente MCP.

Alterar acesso, na página da aplicação, altera mais tarde a que emails acede a chave (Aplicações e chaves).

Boas práticas

• Um token por agente, e uma chave por agente para a organização, para poder revogar um sem parar os outros.
• O acesso mínimo. Dê Responder e escrever emails só a um agente em quem confia para enviar; Deixar rascunhos para aprovação chega para a maioria dos agentes novos.
• Só os endereços que trata. Um agente de suporte vê o suporte@, não o faturacao@.
• Administração só enquanto for precisa, só nas áreas que a tarefa exige, e revogue o token quando o trabalho terminar.
• Uma expiração. 30 ou 90 dias para um token que usa num projeto; Nunca só para um agente que acompanha.
• Segredos fora de ficheiros partilhados. Leia tokens e chaves de variáveis de ambiente ou de um cofre de segredos, nunca de um repositório.
• Reveja as listas. Em Os meus agentes, a Última utilização mostra os tokens que já ninguém usa: revogue-os. Os administradores revêem os tokens de todos em Equipa.

Para programadores (em inglês): MCP server reference e REST API.