Docs
Migrating from v1Health, limits & billing

Health, limits & billing

Health check, rate-limit status and billing in /v2.

This page covers the utility endpoints: the health check, your rate-limit budget, and read-only billing data.

Health check

Tells you whether the API is up. Call it from a monitor, or to check if a failure is the API or your key.

Old APINew API
Method + routeGET /v1/healthGET /v1/health (path unchanged)
Key permission (scope)X-Api-Key header sent in the old exampleno key needed
Rate bucket20/min sharednot rate limited
Plan needed--

What changed

  • The path is still /v1/health. It is the only route that did not move to /v2.
  • Only the host changes: call /v1/health on the new base URL.
  • No key is needed. Do not send one. A monitor can poll it without using your budget.
  • The body is now wrapped in data and meta. The old docs did not document a body at all.

Path and query parameters

None.

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v1/health"

Example request (old)

curl -X GET "https://lupus-edge.trulyinbox.com/v1/health" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new)

200 OK

New field (inside data)TypeWhat it meansOld field
statusstringAlways "ok" when the API answers.not documented in the old docs
timestampstringServer time, ISO 8601 in UTC.not documented in the old docs
{
  "data": {
    "status": "ok",
    "timestamp": "2026-09-29T10:00:00.000Z"
  },
  "meta": {
    "request_id": "req_8c41f0d2-6b1e-4a57-9d3a-2f7e5b0c9a11",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

Not documented in the old docs (the page shows an empty 200 response).

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
500internal_errorThe API is up but something failed.Treat as unhealthy. Retry after a short wait.
--No answer, timeout, or a connection error.Treat as down. Alert or retry later.

Rate-limit status

Shows how much of your per-minute budget is used and left, for each of the three buckets. Call it when you want to plan a batch of calls.

Old APINew API
Method + routeGET /v1/rate-limitGET /v2/workspaces/{workspaceId}/rate-limit
Key permission (scope)any keyany key (no scope needed)
Rate bucketdid not use quota (per old docs)read - this call counts
Plan needed--

What changed

  • The route now sits under a workspace: put your workspaceId in the path.
  • One number became three buckets: read, write, and bulk. Each has its own limit, used, and remaining.
  • This call now uses one request from your read bucket. The old one did not. read.used already includes this call.
  • Limits depend on your organization's plan (see the table below), not a flat 20/min.
  • resetsAt is a Unix time in seconds. All three buckets reset at that moment.
  • Counters are kept per API key. Two keys in the same organization each get their own budget. A separate 100/min limit per IP address applies to all keys together.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyesmust be a workspace your key can accessThe TrulyInbox workspace the key is used for.-

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/42/rate-limit" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X GET "https://lupus-edge.trulyinbox.com/v1/rate-limit" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new)

200 OK

New field (inside data)TypeWhat it meansOld field
read.limitnumberGET requests allowed per minute.not documented in the old docs
read.usednumberGET requests already used this minute (includes this call).not documented in the old docs
read.remainingnumberGET requests left this minute.not documented in the old docs
write.limit / write.used / write.remainingnumberThe same three numbers for POST, PATCH, PUT and DELETE.-
bulk.limit / bulk.used / bulk.remainingnumberThe same three numbers for bulk routes (bulk status, bulk warmup enable/pause, bulk tags).-
resetsAtnumberUnix time in seconds when all buckets reset.not documented in the old docs
{
  "data": {
    "read": { "limit": 20, "used": 7, "remaining": 13 },
    "write": { "limit": 10, "used": 2, "remaining": 8 },
    "bulk": { "limit": 4, "used": 0, "remaining": 4 },
    "resetsAt": 1790676060
  },
  "meta": {
    "request_id": "req_3b9e2a70-11c4-4f0e-8a2d-6c5f1e9d7b20",
    "timestamp": "2026-09-29T10:00:21.000Z"
  }
}

Response (old)

Not documented in the old docs. The old docs only said it returns "requests made, remaining quota, and reset window".

Limits per plan (requests per minute)

Planread (GET)write (POST/PATCH/PUT/DELETE)bulk
Free521
Starter1052
Trial20104
Growth20104
Scale30156
Scale +5k40208
Scale +10k45229
Scale +20k502510

The billing cycle (monthly or yearly) does not change the limit. On top of these, every IP address gets 100 requests per minute across all keys. Tools like Zapier, Make, or n8n may share one IP with other customers, so they can hit the IP limit first.

Headers on every response

HeaderWhat it means
X-RateLimit-LimitLimit of the bucket this call used (read, write, or bulk).
X-RateLimit-RemainingCalls left in that bucket this minute.
X-RateLimit-ResetUnix time in seconds when the window resets.
X-RateLimit-IP-LimitPer-IP limit (100/min).
X-RateLimit-IP-RemainingCalls left for your IP this minute.
Retry-AfterOnly on a 429. Seconds to wait before the next call (at least 1).

How to pace your calls

  1. Read X-RateLimit-Remaining and X-RateLimit-Reset from every response. You do not need to call this endpoint before each request.
  2. If X-RateLimit-Remaining is 0, wait until X-RateLimit-Reset before the next call in that bucket.
  3. Also watch X-RateLimit-IP-Remaining. The IP limit is shared and your plan does not raise it.
  4. On a 429, wait Retry-After seconds (the same value is in error.retry_after). Then retry once.
  5. Do not retry at once in a loop. A rejected call still uses budget, so tight retries keep you blocked.
  6. Keep bulk routes for large jobs. The bulk bucket is small (1 to 10 per minute), but one bulk call can cover many mailboxes.
  7. Five failed key attempts from one IP lock that IP out for 15 minutes (429 too_many_requests). Stop and fix the key instead of retrying.

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorizedNo Authorization: Bearer header.Send the header.
401invalid_api_keyThe key is wrong or was revoked.Use a valid key.
403workspace_forbiddenThe key cannot access this workspaceId.Use the workspace the key belongs to.
403api_access_not_in_planYour plan does not include API access.Upgrade the plan.
403subscription_pausedThe subscription is paused.Resume the subscription.
429rate_limit_exceededThe read bucket or the IP limit is used up.Wait Retry-After seconds, then retry.
429too_many_requestsToo many failed key attempts from your IP.Wait 15 minutes. Fix the key.