API Overview
The Sendook API is a single Cloudflare Worker. Every route is JSON-in / JSON-out, every request authenticates with a Bearer token, and there are exactly two kinds of token: the master key and the per-agent API key.
Base URL
The Worker is reached at whatever route is configured in wrangler.jsonc. For the hosted deployment that's:
https://api.sendook.com
For local development:
http://localhost:8787
Authentication
Every protected route reads Authorization: Bearer <token>. There are two acceptable token kinds:
| Token kind | Where it comes from | What it can do |
|---|---|---|
| Master key | The MASTER_KEY Worker secret. | POST /agents, GET /agents, DELETE /agents/:id, plus everything the per-agent key can do (for any agent). |
| Per-agent API key | Returned exactly once by POST /agents. | All /agents/:id/* routes for its own agent. Cannot create or list agents. |
The agents directory is keyed on a SHA-256 HMAC of the per-agent key (peppered with API_KEY_HASH_PEPPER). The plain key is never stored.
Route map
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /health | none | { ok: true, version } for liveness probes. |
GET | /me | per-agent | Returns the agent identified by the bearer token. |
POST | /agents | master | Create a new agent. Returns the per-agent API key once. |
GET | /agents | master | List every non-tombstoned agent. |
GET | /agents/:id | master / agent's own key | Get a single agent. |
DELETE | /agents/:id | master | Tombstone the agent and purge its DO storage. |
POST | /agents/:id/messages/send | master / agent's own key | Send an email from the agent. |
GET | /agents/:id/messages | master / agent's own key | List the agent's messages (newest first). |
GET | /agents/:id/threads/:threadId | master / agent's own key | Get one thread plus its messages in order. |
POST | /agents/:id/webhooks | master / agent's own key | Create a webhook subscription. Returns the secret once. |
GET | /agents/:id/webhooks | master / agent's own key | List the agent's webhooks (no secrets). |
DELETE | /agents/:id/webhooks/:webhookId | master / agent's own key | Delete one webhook. |
GET | /agents/:id/webhooks/:webhookId/attempts | master / agent's own key | List delivery attempts for one webhook (last 100). |
Agent ids are 12 lowercase alphanumeric chars. UUIDs in webhook ids and thread ids use the standard 8-4-4-4-12 form.
Request format
- All bodies are JSON;
Content-Type: application/jsonis required forPOST/DELETEwith a body. - Body size caps are enforced in UTF-8 bytes, not UTF-16 chars: 4 KiB for
POST /agents, 4 KiB for webhook create, 1 MiB forPOST .../messages/send. - The
POST .../messages/sendbody validates with Zod: addresses are real email addresses,subject≤ 998 chars,text/htmlnon-empty when present, recipients ≤ 50 total, attachments ≤ 10 with eachdata≤ ~5 MiB raw and a strict base64 character set.
Response format
- Success uses
200 OK(read),201 Created(create),202 Accepted(send queued / message persisted),204 No Content(delete). 502 Bad Gatewayis returned forPOST .../messages/sendwhen every recipient was rejected (the per-recipient outcomes are still in the body).- Errors return
application/jsonwith{ "error": "<message>" }and, for Zod failures, an additionaldetailsarray of issues. - Error status codes follow HTTP conventions:
400for validation,401for missing/bad bearer,403for cross-agent access,404for unknown id (or tombstoned agent),500for unexpected.
Example error
{
"error": "invalid request body",
"details": [
{ "code": "invalid_type", "expected": "string", "path": ["subject"] }
]
}
CORS
OPTIONS preflights and the Access-Control-Allow-Origin header are emitted only when the request Origin matches one of the comma-separated values in the ALLOWED_ORIGINS Worker var. Anything else is silently denied — the browser sees no CORS headers and rejects the request. Set ALLOWED_ORIGINS=* to allow any origin (only do this for self-hosted deployments behind another auth layer).