Conecte seu agente
Um app de IA, um script ou o seu próprio código trabalha em um workspace, com uma chave que tem só as permissões e os limites que o dono do workspace escolheu. Toda chamada passa pelas mesmas regras, pelo mesmo registro de envios e pela mesma caixa de entrada do console.
Antes de começar
Você precisa de uma conta no colding aberta pela nossa equipe e de um workspace do qual você seja dono. Só o dono do workspace pode conectar um agente ou criar uma chave de API.
As chamadas de leitura funcionam na hora. As chamadas que enviam e-mail ou acessam outro servidor esperam até o dono do workspace aceitar a política de uso aceitável em Configurações. Até lá, essas chamadas respondem 403 AUP_REQUIRED.
Qualquer app com MCP
Adicione este endereço MCP no seu app de IA e escolha Conectar:
https://api.colding.app/mcpQuando o app pedir, entre na sua conta do colding, escolha o workspace do qual você é dono, marque as permissões e defina os limites que quiser. A permissão Ler (read) já vem marcada para começar. A conexão cria uma chave em Agentes › Chaves de API com as opções que você escolheu.
Se o seu cliente MCP não tiver login OAuth, envie requisições Streamable HTTP sem sessão para o mesmo endereço com Authorization: Bearer cd_your_key em toda chamada.
Um script sem navegador
Quando o seu script roda em um servidor ou terminal sem retorno pelo navegador, peça um código de dispositivo em https://api.colding.app/oauth/device_authorization com client_id=colding-cli e resource=https://api.colding.app/mcp.
Seu script mostra um código curto. Abra https://console.colding.app/auth/device no navegador, entre na sua conta, digite o código e escolha o workspace, as permissões e os limites. Aprove só um código que você mesmo acabou de pedir. O script consulta https://api.colding.app/oauth/token no intervalo indicado até você aprovar.
Seu próprio código
Abra Agentes › Chaves de API no console e crie uma chave só com as permissões de que o seu código precisa. A chave cd_ completa aparece uma única vez. Guarde-a no seu servidor, nunca no código do navegador nem em um repositório público.
Instale o SDK em TypeScript no Node 20 ou mais recente, ou chame a API REST em https://api.colding.app/v1 com Authorization: Bearer cd_your_key:
npm install coldingPermissões por tarefa
Dê a cada chave só as permissões de que a tarefa dela precisa. À esquerda está a tarefa e, à direita, os nomes das permissões como aparecem no console, com o código de cada uma na API:
- Ler sua caixa de entrada
- Ler (
read). Lê conversas, mensagens, caixas de e-mail, contatos, campanhas, verificações, status de envio e eventos sem marcar nada como lido. - Responder aos e-mails
- Ler e Enviar prospecção (
read,send). Marque também Operar (operate) quando o agente criar ou editar rascunhos antes de enviar. - Rodar campanhas
- Ler, Operar e Enviar prospecção (
read,operate,send). Prepara contatos e etapas, inicia campanhas e pausa ou encerra cada uma. - Conferir endereços
- Ler e Conferir endereços (
read,validate). Inicia, repete ou cancela verificações de endereços e lê os resultados. - Enviar e-mail do app
- Enviar e-mail do app (
transactional). Envia recibos, links de acesso e redefinições de senha por uma caixa que você separa para isso, e cancela envios que ainda aguardam. Marque Ler (read) para acompanhar depois. - Conectar caixas e configurar domínios
- Configurar o workspace (
setup). Conecta caixas de e-mail com os logins delas, troca esses logins, confirma o endereço de uma caixa com o código que enviamos para ele, adiciona ou remove domínios de rastreamento e define o endereço postal. Com Ler (read) também, pode configurar e gerenciar um webhook que nenhuma pessoa salvou.
Em Agentes › Chaves de API, ou na tela de autorização OAuth, o dono também pode restringir uma chave a algumas caixas para leitura ou envio, a campanhas específicas, só a prospecção ou só ao e-mail do app, a um limite de envios por dia ou no total, e a uma data de validade.
Etapas que ficam com uma pessoa
Nenhuma chave de API pode entrar com a Microsoft ou o Google, desconectar uma caixa de e-mail, criar ou alterar chaves de API, cuidar da cobrança, aceitar a política de uso aceitável ou alterar ou excluir um webhook que uma pessoa salvou no console. Essas etapas exigem sempre uma pessoa com a sessão iniciada.
Quando um agente chega a uma etapa que exige uma pessoa, uma chave com Operar (operate) e Ler (read) pode abrir uma solicitação com handoffs.create e passar o link do console para o dono ou admin.
Como parar um agente
Para parar um agente na hora, abra a página Agentes no console e clique em Revogar na chave dele, em Agentes › Chaves de API. Toda nova chamada com essa chave é recusada imediatamente, e qualquer e-mail dela que ainda não começou a sair é cancelado antes da entrega.
Para segurar os envios sem revogar a chave, reduza os limites de envio dela em Agentes › Chaves de API, pause uma caixa de e-mail ou uma campanha, ou cancele um envio que ainda aguarda com sends.cancel antes que ele saia.
O que o colding não faz hoje
O colding não dá ao seu agente um endereço de e-mail próprio nos nossos servidores, não envia os e-mails do seu app pelos nossos servidores em nenhum plano à venda, não escreve e-mails sozinho com um modelo de linguagem interno e não oferece um SDK em Python.
Nas caixas de e-mail que você conecta, já é possível anexar arquivos a rascunhos, respostas e e-mails do app. Guarde o arquivo com files.create ou files.createUpload e passe o id dele em fileIds. O envio pelos nossos servidores não aceita anexos.