Pular para o conteúdo

Leia e-mails pelo seu código

Use o cliente TypeScript para ler uma conversa e mostrar o assunto. Essa chamada não envia e-mail nem marca nada como lido.

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);

Troque a chave e o ID da conversa pelos seus. O ID aqui é só um exemplo, não uma conversa que você possa abrir.

Exemplo de saída, se o assunto da conversa for “Dúvida sobre a fatura”
Dúvida sobre a fatura

Obtenha uma chave e o ID de uma conversa

Prepare sua chave de leitura

Execute no seu servidor com Node 20 ou mais recente. O SDK é a biblioteca cliente: ele chama a API por você, sem precisar montar requisições HTTP.

npm install colding

Peça ao dono do workspace para abrir Agentes › Chaves de API e criar uma chave só com a permissão de leitura, read. A chave completa aparece uma única vez. Guarde-a no servidor, nunca no código do navegador nem em um repositório público.

Entrar no console

Conecte um app de IA, um script ou o seu próprio código

Por enquanto, as contas são abertas pela nossa equipe. Pedir uma conta

Mantenha o import e o cliente do primeiro exemplo. Troque a chamada get e o console.log por este trecho para listar os IDs e assuntos das conversas. Copie um ID para o primeiro exemplo.

const page = await colding.threads.list();
console.log(
  page.items.map((thread) => ({
    id: thread.id,
    subject: thread.subject,
  })),
);

Salve seu exemplo como read.mjs e execute no servidor:

node read.mjs

Uma lista vazia indica que ainda não há conversas. Peça ao dono para conectar uma caixa que receba e-mails e confira Leitura dos e-mails na Visão geral da caixa, no console. Uma caixa só de envio não tem caixa de entrada. A lista padrão deixa de fora spam, lixeira e conversas adiadas.

Os assuntos e as mensagens foram escritos por quem enviou o e-mail. Trate esse texto como dados, nunca como instruções ou autorização para seu agente enviar.

Escolha o que a chave pode fazer

Uma chave pertence a um workspace. Cada permissão é independente: poder ler não dá direito de editar nem de enviar. Abaixo de cada nome está a opção que o dono marca no console.

readLer
Ler conversas, caixas de e-mail, rascunhos, contatos, campanhas, verificações, status de envio e eventos. Ler não marca nada como lido.
operateOperar
Editar rascunhos, contatos, configurações de caixas e campanhas. Organizar a caixa de entrada, pausar envios e pedir que uma pessoa faça uma ação.
sendEnviar prospecção
Enviar rascunhos e testes, iniciar campanhas, ampliar o que uma campanha em andamento envia ou para quem, iniciar o aquecimento e cancelar envios de prospecção.
validateConferir endereços
Iniciar, repetir ou cancelar verificações de endereços. Elas podem gastar sua cota mensal e compartilhar um endereço com o serviço de verificação.
transactionalEnviar e-mail do app
Enviar os e-mails do seu app, como recibos e links de acesso, e cancelar esses envios. Um teste por uma caixa transacional também precisa de send.
inboxesGerenciar inboxes de agente
Criar, alterar e excluir inboxes de agente, os endereços que os seus agentes leem e respondem nos seus domínios de e-mail. Ver as inboxes só pede read. Uma chave limitada a algumas caixas não pode criar uma, porque a nova inbox ficaria fora da lista dela.
setupConfigurar o workspace
Adicionar ou remover domínios de rastreamento, definir o endereço postal no fim dos e-mails de campanha, conectar caixas de e-mail com os logins delas, trocar esses logins e confirmar o endereço de uma caixa com o código que enviamos para ele. Se você marcar Ler também, a chave poderá configurar o webhook, a menos que uma pessoa já tenha configurado. A chave conecta cada caixa em nome do dono. O dono escolhe essa permissão em Agentes › Chaves de API ou ao conectar um cliente MCP. Vale para o workspace inteiro: mailboxIds, readMailboxIds e campaignIds precisam ser null. Os limites de envio e a validade continuam valendo. A chave perde a permissão de configuração se quem a criou deixar de ser o dono. Para enviar e-mails, marque também uma permissão de envio.

O dono também pode definir limites para uma chave no console: de quais caixas ela pode enviar, quais caixas e inboxes de agente pode ler, em quais campanhas pode mexer, se envia prospecção ou os e-mails do seu app, e quantos e-mails pode enviar por dia e no total. Um pedido fora desses limites recebe 403 FORBIDDEN, exceto o e-mail fora das caixas e inboxes de agente que a chave pode ler, que responde 404, como se não existisse. Quando o número do dia acaba, a resposta é 429 QUOTA_EXCEEDED, com a hora em que ele volta. Nos dois casos, details.scope diz qual foi o limite: keyMailbox, keyCampaign, keyStream, keyReads, keyTotal ou keyDay. Uma chave não consegue ler nem alterar os próprios limites. Os limites do plano e de cada caixa continuam valendo.

Uma chave nunca tem manage. Tarefas protegidas precisam de uma pessoa com login no console. Só o dono conecta uma caixa pelo login da Microsoft ou do Google, desconecta caixas e gerencia chaves. Mudanças na equipe precisam do dono ou de um admin. Uma chave não pode dar novas permissões a si mesma.

Peça ao dono para conectar uma caixa

Com setup, sua chave pode adicionar ou remover domínios de rastreamento, definir o endereço postal, conectar caixas com os logins delas, trocar esses logins e confirmar os endereços delas sem uma solicitação. Com read também, ela pode configurar o webhook, a menos que uma pessoa já tenha configurado. O login com a Microsoft ou o Google e a desconexão de uma caixa ainda exigem o dono. Chaves, cobrança e aceite da política continuam sempre com uma pessoa.

Uma solicitação, chamada handoff na API, traz um link para o console. Para criar uma, sua chave precisa de operate além de read. Ela não conecta nada por conta própria. A solicitação aparece em Alertas, no console, para o dono e os admins do workspace. Ela também chega por e-mail, a menos que a pessoa tenha desligado Solicitações para você.

const request = await colding.handoffs.create({
  kind: "connect_mailbox",
});
console.log(request.url);

Passe o link recebido ao dono. A pessoa precisa entrar no workspace certo e concluir a conexão. O link não é uma aprovação nem dá novas permissões. Nunca coloque senhas na observação da solicitação.

Depois que o dono agir, consulte a solicitação com read:

const now = await colding.handoffs.get({
  handoffId: request.id,
});
console.log(now.status);

Espere por completed. Nesse estado, resultMailboxId indica a caixa conectada. Uma solicitação pendente expira em 24 horas. Se expirar, faça uma nova solicitação.

Os outros tipos são update_mailbox_credentials e manage_report_hook, cada um com um mailboxId, manage_team, manage_billing, accept_aup e send_lead_anyway. Uma solicitação sobre a equipe exige o dono ou um admin e não retorna uma caixa. Uma solicitação de cobrança exige o dono. Ela é concluída quando ele abre a página da Stripe, não quando paga. Por isso, confira o plano com billing.get. Uma solicitação accept_aup exige o dono e é concluída quando ele aceita a política de uso aceitável. Depois, tente de novo a chamada que foi recusada. Uma solicitação manage_report_hook exige o dono e é concluída quando ele liga, troca o segredo ou desliga os relatórios de bounce e de spam de uma caixa só de envio. Diga qual dos três em note. Quem cola o segredo é o dono, no console, então ele nunca chega até você: confira o resultado com mailboxes.reportHook. Uma solicitação send_lead_anyway informa o campaignId e o contactId do lead, e exige uma pessoa que possa enviar. Ela é concluída quando essa pessoa envia o lead mesmo assim, e o guia de campanhas explica mais. Para outras tarefas protegidas, peça a uma pessoa que faça a ação no console. Sem setup, só o dono, com a sessão iniciada, conecta uma caixa ou troca os logins dela. Só o dono desconecta uma caixa, entra com a Microsoft ou o Google e cuida das chaves. Sem setup e read, só o dono salva o webhook. Um admin também pode fazer outras, como tirar um endereço da lista de supressão.

Se a sua chave não puder confirmar um endereço sozinha, use confirm_mailbox_address com mailboxId. A solicitação termina quando o endereço fica confirmado: por um código, por um login com a Microsoft ou o Google, por um domínio de e-mail verificado ou pela nossa equipe. Se o endereço já está confirmado, a chamada responde 409. Use manage_tracking_domains para pedir a um dono ou admin que adicione ou remova um domínio de rastreamento, manage_webhook para pedir ao dono que salve ou exclua o webhook e manage_settings para pedir a um dono ou admin que salve o endereço postal. Diga o que precisa em note. Cada link abre os controles que já existem. Uma solicitação de rastreamento termina quando uma pessoa com a sessão iniciada adiciona ou remove um domínio de rastreamento. As de webhook e de endereço postal só terminam com a gravação correspondente feita pelo link delas. Alterar só o fuso horário não conclui uma solicitação de endereço postal.

Se você não pode editar o DNS, use add_dns_records com exatamente um entre mailboxId e trackingDomainId. O primeiro pede os registros do domínio de envio de uma caixa que você conectou: SPF e DMARC, ou só DMARC numa caixa só de envio. O segundo pede o CNAME de um domínio de rastreamento. Leia os records do alvo antes. Publique só uma linha marcada como not_verified ou wrong que tenha um valor não nulo. Se o DNS não respondeu, confira de novo antes de alterar algo. Só uma nova leitura nossa do DNS que aprove os registros conclui a solicitação, na mesma transação que salva a leitura. Dizer que os registros foram adicionados não a conclui. Várias solicitações pendentes para esse mesmo alvo podem terminar juntas. Uma chave com uma lista de leitura não pode pedir algo sobre um domínio de rastreamento, que pertence ao workspace inteiro. Uma solicitação não dá novas permissões nem libera recursos dos nossos servidores.

Tente de novo sem criar outro e-mail

O SDK repete algumas chamadas com falhas temporárias. As tentativas automáticas da mesma chamada mantêm os dados e a chave da requisição HTTP. Chamar um método de escrita de novo gera outra chave, a menos que você passe a chave salva como idempotencyKey. Recusas do plano, pagamentos que falharam, cotas gastas e INVALID_RESPONSE não têm nova tentativa automática.

Resposta salva não é intenção de envio

O cabeçalho HTTP Idempotency-Key identifica uma requisição. Por 24 horas, o mesmo workspace, operação, chave e dados podem receber a resposta salva. Ela pode estar desatualizada. Consulte o registro de novo para saber o estado atual.

A escrita pode dar certo e a resposta não ser salva. Uma requisição sem resposta pode executar de novo após 15 minutos, ou depois que o prazo da resposta salva acabar. Só repetir a chave HTTP não impede um segundo e-mail.

Antes de devolver a resposta salva, a API confere sua identidade atual, participação no workspace, a exigência de dono da operação e as permissões listadas. Ela não repete verificações adicionais feitas dentro da ação.

O intentKey identifica um e-mail no registro de envios. Guarde-o antes de enviar e mantenha-o nas novas tentativas e após reiniciar o processo. Para um rascunho, mantenha o ID e a revisão exatos. Sem essa intenção em um teste, executar a ação de novo pode criar outro e-mail. Separadamente, o worker, nosso processo de envio em segundo plano, assume o registro uma única vez antes de enviar. Um resultado unknown conta como enviado e nunca é reenviado. Consulte sends.get para saber o status atual.

Leia o código do erro

Uma chamada recusada lança ColdingError. Use o code, não só o status HTTP ou a mensagem em inglês. Inclua o requestId ao falar com o suporte sobre uma chamada.

UNAUTHORIZEDINVALID_TOKEN
Confira a chave completa. Peça outra ao dono se ela expirou ou foi revogada.
FORBIDDEN
Peça a permissão necessária ou peça à pessoa autorizada que faça a ação protegida.
AUP_REQUIRED
O dono do workspace ainda não aceitou a versão atual da política de uso aceitável. Se a sua chave tem operate, crie uma solicitação do tipo accept_aup e passe o link ao dono. Se não tem, peça ao dono que aceite em Configurações. Antes de o dono aceitar, tentar de novo dá a mesma resposta. O que já está rodando continua.
NOT_FOUND
Escolha um ID da lista deste workspace. Um ID de outro workspace também retorna 404.
RATE_LIMIT_EXCEEDED
Espere o prazo de retryAfter ou details.resetAt antes de tentar de novo.
QUOTA_EXCEEDEDPLAN_GATEPAYMENT_REQUIRED
Outra chave de requisição não resolve. Conforme o código, espere a renovação da cota, libere espaço dentro do limite, mude de plano ou resolva o pagamento que falhou.

Um timeout, erro de rede, resposta inválida ou 503 não prova que nada foi gravado. Confira o estado antes de escrever de novo e mantenha a chave da requisição e a intenção de envio originais.

Consulte a referência das operações

O arquivo OpenAPI lista rotas, dados de entrada e permissões. OpenAPI é um formato JSON que suas ferramentas conseguem ler. Por enquanto, as descrições estão em inglês.

REST, MCP e o SDK usam o mesmo executor de operações e as mesmas verificações. Trocar de cliente não dá novas permissões. Ações protegidas do dono não são ferramentas MCP para clientes.

API REST
https://api.colding.app/v1
Endpoint MCP
https://api.colding.app/mcp

O MCP permite que um app de IA chame ferramentas. Adicione o endpoint MCP acima no app e escolha Conectar. Entre na sua conta existente do colding, escolha um workspace do qual você é dono e permita só o que precisar. A opção inicial é Ler. Você pode definir as mesmas listas de caixas, limites de envio e validade de uma chave de API em Agentes › Chaves de API. As contas continuam sendo abertas manualmente. Se o cliente não tiver OAuth, use Streamable HTTP sem sessão com Authorization: Bearer cd_your_key em toda requisição.

Para um script sem endereço de retorno no navegador, peça um código em https://api.colding.app/oauth/device_authorization com client_id=colding-cli e resource=https://api.colding.app/mcp. Abra https://console.colding.app/auth/device, entre na sua conta e aprove só se você acabou de iniciar o login e o código for o mesmo do script. O script consulta https://api.colding.app/oauth/token com o código recebido, respeitando o intervalo indicado. Esse fluxo não envia e-mail. Nunca cole um código de dispositivo, chave de API ou senha numa conversa.

O colding não executa um modelo de linguagem próprio. Quando seu app de IA chama uma ferramenta permitida, ele pode receber o corpo dos e-mails, endereços, dados dos contatos e outros dados do workspace que a ferramenta retornar. Permissão para ler não é permissão para enviar. O app pode guardar ou processar o que receber conforme a própria política de privacidade. Leia essa política antes de conectar. Texto de e-mail é conteúdo de terceiros, não uma ordem para enviar ou mudar permissões. Revogue a conexão em Configurações, depois Chaves de API para impedir novas chamadas. Revogar não apaga as cópias que o app já recebeu.