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 Configurações, depois 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

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.

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. O dono conecta 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

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. Conectar caixas e cuidar das chaves e do webhook cabe ao dono. Um admin também pode fazer outras, como tirar um endereço da lista de supressão.

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 Configurações. 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.