Read your workspace, team and alerts

A key works in one workspace. These calls say which workspace that is, who is in it and what needs a person. They only read, except the one that marks alerts as read. Start with the workspace itself. This changes nothing.

Your workspace

import { Colding } from "colding";

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

Replace the key with yours. It prints the workspace's name and its plan.

Acme Studio free

The answer also holds the workspace's slug, locale and timezone, and senderPostalAddress, the address printed under every campaign email.

role is the role of the member who made the key, as it is today: owner, admin or member.

aup.required is the version of the acceptable use policy we ask for, and aup.version is the one an owner accepted, or null. While they differ, a call that sends mail or reaches another server answers 403 AUP_REQUIRED. Only an owner can accept it. Ask with an accept_aup handoff.

posture is null unless we limited what the workspace sends. Then it holds the level and, when we kept one, a reasonCode or a reason. At restricted, campaigns, messages and transactional email wait, and warmup goes on. At suspended, nothing goes out, warmup included. Reading and incoming mail go on in both. The workspace.posture_changed event says when it changes.

deletion is null unless an owner asked to delete the workspace. Then it holds requestedAt and purgeAt, 30 days apart, and nothing goes out until the owner cancels.

A key can't rename the workspace, change its time zone, language or postal address, accept the policy, download all its data or ask to delete it. A key never holds manage, so a person does these in the console. Only an owner accepts the policy, downloads the data and deletes the workspace.

Team

team.get counts the seats the workspace uses against its plan. team.listMembers lists the members, newest first.

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

occupiedSeats adds the members and the pending invitations, because an invitation holds a seat until it is accepted, revoked or expired. seatLimit is the plan's limit, or null when the plan sets none. The answer also holds members, pendingInvitations, the plan and the role of the member who made the key.

Each member has userId, email, name (or null), role and joinedAt. Any key that can read sees the members' email addresses. The list is paged: pass nextCursor back as cursor.

A key can't invite someone, change a role, remove a member or transfer ownership. Those need manage, and an owner or admin does them in Settings. Only an owner invites an admin or changes an admin's role, and only an owner transfers ownership. To ask for one, open a manage_team handoff and say what you want in note:

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

It completes when the person makes the change, and it lasts 24 hours. Read the team again to see the result.

An invitation link is for the person it names. They open it in the console, signed in with that verified email, and accept it there. The SDK has no call for it, because a key can't accept an invitation for someone. To add someone, ask for a manage_team handoff.

Alerts

An alert says something needs a person: a mailbox in trouble, a campaign we paused, a reply, a request. Every person has their own alerts, and a key reads those of the member who made it. This lists the unread ones and marks them read:

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

Alerts come newest first. unread in the answer counts every unread alert, not only this page's. Listing marks nothing read.

kind says what happened, and params holds what to open: a mailbox, a campaign, a thread, a draft, a handoff, a tracking domain or an import, by ID.

mailbox_failed

A mailbox stopped working. params.code says why.

mailbox_health

A mailbox's warmup health got worse, or a quarantine or block started a new term.

campaign_paused

We paused a campaign. params.reason says why. A pause by a person raises no alert.

reply_received

A person answered a campaign email or a message sent from the workspace. Never an away message, another machine or a request to stop.

draft_review

Someone asked a person to review a draft.

handoff_requested

An agent asked a person to do what a key can't.

domain_grace_ending

A sending domain has failed its SPF or DMARC records for most of its grace. When the grace ends, warmup and campaigns stop sending from its mailboxes.

mailbox_full

A Microsoft 365 mailbox is full and sends nothing until someone makes room.

relay_gave_up

A change made in the Inbox, such as marking read or a move, that the mailbox kept refusing for a day. We gave it up.

tracking_domain_failing

The workspace's tracking domain stopped pointing at us. Tracking is off until it points back.

campaign_checks_held

A running campaign's new leads wait, because their address checks can't run. params.reason says why.

workspace_posture

We limited what the workspace sends, or lifted the limit.

webhook_disabled

We switched the workspace's webhook off because its deliveries failed for days.

email_check_run_held

A batch of address checks that a person or a key started has nothing moving, and what is left waits on hold. params.reason says why. It raises one alert each time a batch goes on hold, and the checks start again by themselves.

mail_domain_problem

A mail domain you added has a problem, or is on hold. params.problem is failing (its records stopped verifying), grace_ending (mail sent from the domain stops soon), mx_moved (its MX record no longer points at us), under_review (email from every sender address on the domain is on hold while our team reviews it) or review_ended (the hold is over). params.ground says why a hold began and is null on the others. params.endsAt is when mail sent from the domain stops, or null.

agent_storage_full

The mail your agent inboxes store is at your plan's limit. Mail sent to them is refused until you delete an inbox or your plan changes.

mailbox_address_claimed

A mailbox you connected was disconnected because another workspace proved it controls the address's domain. params.address is the address and params.domain is the domain.

mailbox_under_review

We limited a mailbox, or lifted the limit. params.state is held or released (the review is over and nothing limits the mailbox now). On held, params.mode says which limit: hold (nothing sends from the mailbox, and it still gets mail unless params.receiving is true: then email sent to it goes back to the sender) or first_contact_brake (an agent inbox still replies to people your workspace wrote to before, but not to anyone new). On a hold, params.ground says why: spam_reports, phishing_malware, legal_order or other when our team held the mailbox after a report about it, or complaint_rate, bounce_rate, policy_bounce_rate or policy_abuse_burst when too many emails from the domain in params.address were marked as spam, bounced or refused as spam, so every agent inbox on that domain is on hold. Otherwise it is null. params.caseNumber is the number to quote when you write to us, and params.until is the date we said we would review by.

alerts.markRead needs operate. Pass through with the newest alert you saw, and it marks that alert and every older one read. An alert that came after it stays unread. Or pass up to 100 IDs in ids. IDs that are not yours, or are already read, are left alone. Pass one of the two, not both. marked in the answer counts the alerts that changed.

A key marking an alert read never stops the email the person gets about it. Only reading it in the console does.

Alerts are for people. To have your own server told when something happens, use events.

Read how to receive events on your server