Ops API reference

The relay's fetch() handler is a small JSON API for operators and scripts: list tenants and their queues, read a stored message, requeue what failed, and delete what should not be delivered. It is not meant for browsers, so there are no cookies, no CORS and no content negotiation.

Access

• GET /health is public and answers {"ok":true}. It says nothing else, so it is enough for an uptime check and not enough to learn what the Worker is.

• Every other route needs Authorization: Bearer <OPS_TOKEN>. The token is the Worker secret OPS_TOKEN and must be at least 32 characters.

• One token per Worker. The operator runs every tenant, and no tenant ever receives ops access to a shared relay.

• While OPS_TOKEN is unset, blank or shorter than 32 characters, every route except /health answers 404, the same as any unknown path. A too-short token also logs ops_token_too_short, so a truncated paste never protects a relay with a few characters.

• With a valid token configured, a missing or wrong bearer token gets 401 with a WWW-Authenticate: Bearer header. The comparison is constant-time.

The API lives on the Worker's workers.dev hostname. For another layer, put a Cloudflare Access policy in front of it, either an Access application on that hostname or workers_dev: false plus a custom route behind Access. No code change is involved.

The examples below use <RELAY_HOST> for the Worker's hostname and <SLUG> for a tenant's slug. A route whose slug is not in the tenant table, or whose message ID is not a valid ULID, answers 404.

Routes

Listing

curl -H "Authorization: Bearer <OPS_TOKEN>" https://<RELAY_HOST>/tenants
curl -H "Authorization: Bearer <OPS_TOKEN>" "https://<RELAY_HOST>/tenants/<SLUG>/inbox?status=pending&limit=20"

GET /tenants answers {"ok": true, "items": [...]}, where each item is the tenant's row from tenants.json with every default applied (slug, platform, domains, enabled, note, the retention, attempt, backoff and timeout settings) plus its counts. GET /tenants/<SLUG> answers {"ok": true, "item": {...}} in the same shape.

The inbox listing answers {"ok": true, "items": [...]}. status is one of the four states below; any other value answers 400 invalid status. limit defaults to 50 and is capped at 500, and a value that is not a positive whole number falls back to the default instead of failing.

Retrying and deleting

curl -X POST -H "Authorization: Bearer <OPS_TOKEN>" https://<RELAY_HOST>/tenants/<SLUG>/inbox/<ID>/retry
curl -X POST -H "Authorization: Bearer <OPS_TOKEN>" "https://<RELAY_HOST>/tenants/<SLUG>/inbox/retry?status=dead"
curl -X DELETE -H "Authorization: Bearer <OPS_TOKEN>" https://<RELAY_HOST>/tenants/<SLUG>/inbox/<ID>

• A retry gives the row its full attempt budget back: the attempt count returns to 0, the next attempt is due at once and any purge date is cleared. It answers 202 with {"ok": true, "id": "<ID>"}.

• A row that is already pending is left alone and answers 409 already pending. Its attempt may be in flight, and resetting it could deliver the message twice. This is expected, not an error to fix.

• The bulk retry answers 202 with {"ok": true, "status": "<status>", "requeued": <count>}. Any other status answers 400 status must be dead or rejected.

• Delete removes the R2 object first, then the row. If the object cannot be deleted the row survives, so a failure is visible rather than leaving an orphan in the bucket.

Use a retry after you fix the cause: a rotated secret, a corrected inboundUrl, an ERP that is back up. Retrying without fixing it only reproduces the failure.

The four states

A queue row

The inbox routes answer rows with these fields. Timestamps are milliseconds since the Unix epoch.

A delivered row with an empty remoteRef is not an error. The ERP answered 2xx and chose to ignore the message: a duplicate, a bounce, or its own outgoing mail looping back.

Log events

The Worker writes one JSON line per event, so Workers Logs can filter on the event field and on any other field. The example configuration turns observability on, and npx wrangler tail streams the same lines. Events carry ids, addresses, statuses and counts, never a message body, a secret or the inbound URL.

Related

• Troubleshooting: which event or status to look at for each symptom.

• Tenants and secrets: the settings behind retention, backoff and the attempt limit.

• Inbound contract: how a status code from the ERP becomes a row state.