Leia seu workspace, a equipe e os alertas

Uma chave trabalha em um workspace. Estas chamadas dizem qual é ele, quem está nele e o que precisa de uma pessoa. Elas só leem, exceto a que marca alertas como lidos. Comece pelo próprio workspace. Isto não muda nada.

Seu workspace

import { Colding } from "colding";

const colding = new Colding("cd_your_key");
const workspace = await colding.workspace.get();
console.log(workspace.name, workspace.plan);

Troque a chave pela sua. Ele mostra o nome e o plano do workspace.

Acme Studio free

A resposta traz também o slug, o locale e o timezone do workspace, e o senderPostalAddress, o endereço impresso embaixo de cada e-mail de campanha.

O role é a função de quem criou a chave, como ela está hoje: owner, admin ou member.

O aup.required é a versão da política de uso aceitável que pedimos, e o aup.version é a que um dono aceitou, ou null. Enquanto as duas forem diferentes, uma chamada que envia e-mail ou acessa outro servidor responde 403 AUP_REQUIRED. Só um dono pode aceitar. Peça com um handoff accept_aup.

O posture é null enquanto nada limita o que o workspace envia. Quando algo limita, ele traz o level e, se houver um motivo, um reasonCode ou um reason. Em restricted, campanhas, mensagens e e-mail transacional ficam em espera, e o aquecimento continua. Em suspended, nada sai, nem o aquecimento. Nos dois, a leitura e o recebimento de e-mail continuam. O evento workspace.posture_changed avisa quando isso muda.

O deletion é null, a menos que um dono tenha pedido para excluir o workspace. Aí ele traz requestedAt e purgeAt, com 30 dias entre os dois, e nada sai até o dono cancelar.

Uma chave não pode renomear o workspace, mudar o fuso horário, o idioma ou o endereço postal, aceitar a política, baixar todos os dados dele nem pedir a exclusão. Uma chave nunca tem manage, então uma pessoa faz isso no console. Só um dono aceita a política, baixa os dados e exclui o workspace.

Equipe

O team.get conta os lugares que o workspace usa em relação ao plano. O team.listMembers lista os membros, dos mais recentes para os mais antigos.

const team = await colding.team.get();
console.log(team.occupiedSeats, team.seatLimit);

const page = await colding.team.listMembers({ limit: 20 });
for (const member of page.items) console.log(member.email, member.role);

O occupiedSeats soma os membros e os convites pendentes, porque um convite ocupa um lugar até ser aceito, revogado ou expirar. O seatLimit é o limite do plano, ou null quando o plano não define nenhum. A resposta traz ainda members, pendingInvitations, o plano e a função de quem criou a chave.

Cada membro tem userId, email, name (ou null), role e joinedAt. Qualquer chave que possa ler vê os e-mails dos membros. A lista é paginada: passe o nextCursor de volta como cursor.

Uma chave não pode convidar alguém, mudar uma função, remover um membro nem transferir a propriedade. Isso exige manage, e um dono ou um admin faz em Configurações. Só um dono convida um admin ou muda a função de um admin, e só um dono transfere a propriedade. Para pedir uma dessas ações, abra um handoff manage_team e diga o que você quer em note:

const request = await colding.handoffs.create({
  kind: "manage_team",
  note: "Invite [email protected] as a member.",
});
console.log(request.url);

Ele é concluído quando a pessoa faz a mudança, e vale por 24 horas. Leia a equipe de novo para ver o resultado.

O link de um convite é da pessoa convidada. Ela precisa entrar no console com o e-mail verificado que o convite indica e aceitar por lá. O SDK não tem uma chamada para isso, porque uma chave não aceita um convite no lugar de ninguém. Para adicionar alguém, peça um handoff manage_team.

Alertas

Um alerta avisa que algo precisa de uma pessoa: uma caixa com problema, uma campanha que pausamos, uma resposta, um pedido. Cada pessoa tem os seus alertas, e uma chave lê os de quem a criou. Este código lista os não lidos e os marca como lidos:

const page = await colding.alerts.list({ unread: true });
console.log(page.unread);
for (const alert of page.items) console.log(alert.kind, alert.createdAt);

const newest = page.items[0];
if (newest) await colding.alerts.markRead({ through: newest.id });

Os alertas vêm do mais novo para o mais antigo. O unread da resposta conta todos os alertas não lidos, não só os desta página. Listar não marca nada como lido.

O kind diz o que aconteceu, e o params traz o que abrir: uma caixa, uma campanha, uma conversa, um rascunho, um handoff, um domínio de rastreamento ou uma importação, pelo ID.

mailbox_failed

Uma caixa parou de funcionar. O params.code diz o motivo.

mailbox_health

A saúde de uma caixa no aquecimento piorou, ou uma quarentena ou um bloqueio começou um novo período.

campaign_paused

Pausamos uma campanha. O params.reason diz o motivo. Uma pausa feita por uma pessoa não gera alerta.

reply_received

Uma pessoa respondeu a um e-mail de campanha ou a uma mensagem enviada pelo workspace. Nunca uma mensagem de fora do escritório, outra máquina ou um pedido para parar.

draft_review

Alguém pediu a uma pessoa que revisasse um rascunho.

handoff_requested

Um agente pediu a uma pessoa o que uma chave não pode fazer.

domain_grace_ending

Um domínio de envio está com os registros SPF ou DMARC falhando há quase todo o prazo de tolerância. Quando ele acabar, o aquecimento e as campanhas deixam de enviar pelas caixas desse domínio.

mailbox_full

Uma caixa do Microsoft 365 está cheia e não envia nada até alguém abrir espaço.

relay_gave_up

Uma mudança feita na caixa de entrada, como marcar como lida ou mover, que a caixa recusou por um dia. Desistimos dela.

tracking_domain_failing

O domínio de rastreamento do workspace deixou de apontar para nós. O rastreamento fica desligado até ele voltar a apontar.

campaign_checks_held

Os novos leads de uma campanha em andamento esperam, porque as verificações dos endereços não podem rodar. O params.reason diz o motivo.

workspace_posture

Limitamos o que o workspace envia, ou tiramos o limite.

webhook_disabled

Desligamos o webhook do workspace porque as entregas falharam por dias.

email_check_run_held

Um lote de verificações de endereço que uma pessoa ou uma chave iniciou não está andando, e o que sobrou fica em espera. O params.reason diz o motivo. Cada vez que um lote entra em espera, sai um alerta, e as verificações voltam sozinhas.

mail_domain_problem

Um domínio de e-mail que você cadastrou tem um problema ou está em espera. O params.problem é failing (os registros deixaram de ser verificados), grace_ending (o envio de e-mail pelo domínio vai ser interrompido em breve), mx_moved (o registro MX não aponta mais para nós), under_review (os e-mails de todos os endereços de remetente do domínio estão em espera enquanto nossa equipe analisa) ou review_ended (a espera terminou). O params.ground diz por que a espera começou e é null nos outros. O params.endsAt é a hora em que o envio de e-mail pelo domínio é interrompido, ou null.

agent_storage_full

O e-mail guardado nas suas inboxes de agente chegou ao limite do plano. Os e-mails enviados para elas são recusados até você excluir uma inbox ou o plano mudar.

mailbox_address_claimed

Uma caixa que você conectou foi desconectada porque outro workspace comprovou que controla o domínio do endereço. O params.address é o endereço e o params.domain é o domínio.

mailbox_under_review

Limitamos uma caixa, ou tiramos o limite. O params.state é held ou released (a análise terminou e nada mais limita a caixa). Em held, o params.mode diz qual é o limite: hold (nada sai da caixa, e ela continua recebendo, a menos que params.receiving seja true: aí os e-mails enviados para ela voltam para quem enviou) ou first_contact_brake (uma inbox de agente ainda responde a quem seu workspace já escreveu antes, mas não a contatos novos). Numa espera, o params.ground diz o motivo: spam_reports, phishing_malware, legal_order ou other quando nossa equipe colocou a caixa em espera depois de uma denúncia sobre ela, ou complaint_rate, bounce_rate, policy_bounce_rate ou policy_abuse_burst quando e-mails demais do domínio de params.address foram marcados como spam, deram bounce ou foram recusados como spam, e por isso todas as inboxes de agente desse domínio estão em espera. Nos outros casos, ele é null. O params.caseNumber é o número do caso, para citar quando você escrever para a gente, e o params.until é a data até a qual dissemos que ia analisar.

O alerts.markRead exige operate. Passe through com o alerta mais novo que você viu, e ele marca esse alerta e todos os mais antigos como lidos. Um alerta que chegou depois continua não lido. Ou passe até 100 IDs em ids. IDs que não são seus, ou que já estão lidos, ficam como estão. Passe um dos dois, não os dois. O marked da resposta conta os alertas que mudaram.

Uma chave que marca um alerta como lido não impede o e-mail que a pessoa recebe sobre ele. Só lê-lo no console impede.

Alertas são para pessoas. Para o seu servidor ser avisado quando algo acontece, use eventos.

Veja como receber eventos no seu servidor