Check your workspace from code: Koltrix API health, domains and usage

Call three: how close am I to the limits?#

GET /usage shows how much of the plan the workspace has used.

{
  "plan": "growth",
  "trial": false,
  "storage": { "used": 1288490188, "limit": 53687091200, "percent": 2 },
  "api_sends_monthly": { "used": 3120, "limit": 50000, "window": "month", "percent": 6 },
  "mailboxes": { "used": 4, "limit": 10, "percent": 40 },
  "seats": { "used": 3, "limit": 5, "percent": 60 }
}

Each figure has used, limit and percent, and the sending figures also have a window (a day or a month). Two details to handle in code:

• A limit of -1 means unlimited. Check for it before you divide, or you will report nonsense percentages.
• trial tells you the workspace is still on a trial. A trial workspace is the one most likely to hit a wall, so it deserves a lower alert threshold.

A reasonable rule is a warning at 80 percent and an alert at 95 percent, using the percent field the API already gives you. Warn early enough that a person can add capacity or clean up before it matters. For what to do when a send is refused by a limit, see handling 429 errors.

Call four: are my templates there?#

GET /templates returns the saved templates, with name, category, subject, body_html, body_text and timestamps, and GET /templates/:id returns one. This is useful in two places:

• A deploy check. If your application expects a template named "Pricing question" and it is missing, you want to know before a customer replies.
• A backup. The response contains the full text, so a nightly job can save it to your own storage.

Pass a malformed id to /templates/:id and you get a 404, not a server error, so a bad id from a stale config is easy to recognize.

Putting it together: a small health check#

Here is a shell sketch that combines the first three calls. It prints one line per problem and exits non-zero when something needs attention, so a scheduler or a monitoring tool can act on it.

#!/usr/bin/env bash
set -u
api=https://api.koltrix.com/api/v2
auth="Authorization: Bearer $KOLTRIX_API_KEY"
bad=0

me=$(curl -sf -H "$auth" "$api/me") || { echo "me: request failed"; exit 2; }
[ -n "$(echo "$me" | jq -r .read_only_reason)" ] && { echo "workspace is read-only: $(echo "$me" | jq -r .read_only_reason)"; bad=1; }

curl -sf -H "$auth" "$api/domains" | jq -r '.data[] | select(.ready|not) | "domain not ready: \(.domain)"' | grep . && bad=1

curl -sf -H "$auth" "$api/usage" | jq -r 'to_entries[] | select(.value|type=="object" and .percent != null) | select(.value.limit != -1 and .value.percent >= 90) | "usage \(.key) at \(.value.percent)%"' | grep . && bad=1

exit $bad

Run it every hour from a scheduler, and send the output to wherever your team already looks. Keep the key in a secret store, and give it only the scopes it needs. A key for this job needs read and nothing more, which is the principle behind API key security.

What this does not do#

It is worth being clear about the limits of these calls.

• They do not send mail. Sending is a separate call with the send scope, and it should always carry an idempotency key, as covered in idempotency keys for email sends.
• They do not prove a message arrived. A ready domain means your records are in place, not that a particular message reached an inbox. For delivery of one message, read the message log and its events.
• They show the workspace, not other workspaces. One key sees one workspace.

A short checklist#

1. Make a key with only the read scope for monitoring.
2. Call /me first, and check tenant, permissions and read_only_reason.
3. Loop through /domains and alert on the exact record that is missing.
4. Read /usage, handle a limit of -1, and warn before 100 percent.
5. Check that the templates your code depends on still exist.
6. Run the check on a schedule and send failures to a place people read.
7. Keep the key in a secret store and rotate it if it leaks.

Key takeaways#

A few read-only calls give your own code the same view a person gets in the Koltrix settings: who the key is, whether the workspace can send, whether each domain is ready and how much of the plan is left. Check them on a schedule, alert on the specific problem and give the monitoring key only the read scope. You will hear about a lost DNS record or a nearly full limit from your own script, not from a customer.