Timerbeam API

Quick start

1. Create a key on the API keys page of your dashboard.
2. Create a timer:

curl https://api.timerbeam.com/api/timers \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "label": "Black Friday",
    "deadline": "2026-11-27T23:59",
    "timezone": "Europe/Budapest",
    "template": "cards",
    "store": true
  }'

You get the timer back — its image URL and the ready-to-paste email HTML:

{
  "id": "k7Qm2xPa9Lz3",
  "imageUrl": "https://api.timerbeam.com/s/k7Qm2xPa9Lz3.gif",
  "html": "<a href=\"…\"><img src=\"…/s/k7Qm2xPa9Lz3.gif\" width=\"570\" height=\"134\" …></a>",
  "deadline": "2026-11-27T22:59:00.000Z",
  "opens": 0,
  …
}

Put html in your email (or point an image block at imageUrl). Change the timer later with PATCH /api/timers/{id} — every email already sent shows the change on its next open.

Authentication

Send your key as Authorization: Bearer tb_live_…. A key acts as its account: its timers, its brand kits, its plan’s limits and features. A read-only key can only use GET. No key can sign in, touch billing, delete the account or manage keys — those stay in the dashboard. Revoke a key there and it stops working at once.

Without a key, POST /api/timers still works: a one-off timer (baked into its link, not editable), or with "store": true a saved timer whose manageKey — returned once — authorises its own GET/PATCH/DELETE.

Time zones

Give deadline as local time and name the zone: "deadline": "2026-11-27T23:59", "timezone": "Europe/Budapest" — daylight saving included. Or send an absolute time: ISO 8601 with an offset (2026-11-27T22:59:00Z) or unix seconds. Responses always give deadline in UTC.

Templates & brand kits

GET /api/templates lists the starting designs. Pass one as template, and a brand kit as brandKit to put it in your colours and font — in the same call:

{ "deadline": "2026-11-27T23:59", "timezone": "Europe/Budapest",
  "template": "cards", "brandKit": "<id from GET /api/brand-kits>", "store": true }

Or send a full design (see TimerDesign in the OpenAPI document). Templates marked proFont use a font from the Pro plan and up; brand kits are Business.

Evergreen timers

A countdown per recipient instead of one deadline (Pro and up, saved timers only):

{ "label": "Welcome offer", "store": true,
  "evergreen": { "durationSeconds": 172800, "start": "first-open" } }

The returned html carries ?r=RECIPIENT_ID (or ?start=START_DATE for "url-date") — swap the placeholder for your email platform’s merge tag. The email platform guides list the tags for Klaviyo, Mailchimp, HubSpot and Brevo.

Idempotency

Send an Idempotency-Key header (a UUID) with POST /api/timers. If the request is retried — a timeout, a crash, an agent trying again — the same key and body return the first answer (with Idempotent-Replayed: true) instead of creating a second timer. Keys are kept 24 hours; the same key with a different body is a 422. A replay never repeats a manage key.

Errors & limits

Every error is JSON: { "error": "<code>", "message": "<what to fix>" } — branch on error, show message.

Each key has its own rate budget; X-RateLimit-Remaining on every keyed response says what’s left. Plan limits (saved timers, fonts, evergreen, brand kits) apply exactly as in the editor — see pricing.

Analytics

On Business, GET /api/stats gives the account’s opens by day and by timer, and GET /api/timers/{id}/stats one timer’s — any range within the last year, every day included (zeros too), in UTC. Without from/to, the last 30 days.

curl "https://api.timerbeam.com/api/stats?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer tb_live_…"

{
  "from": "2026-11-01", "to": "2026-11-30", "total": 48210,
  "days": [{ "day": "2026-11-01", "count": 0 }, …, { "day": "2026-11-27", "count": 19344 }, …],
  "timers": [{ "id": "k7Qm2xPa9Lz3", "label": "Black Friday", "opens": 41022 }, …]
}

Webhooks

On Business, Timerbeam can tell your own systems what happens — add endpoints on the Webhooks page or with POST /api/webhooks. Each event is a JSON POST:

POST https://example.com/timerbeam-webhook
webhook-id: evt_4f0c2a…
webhook-timestamp: 1795820340
webhook-signature: v1,Zr0cBC5v…

{
  "id": "evt_4f0c2a…",
  "type": "timer.expired",
  "createdAt": "2026-11-27T22:59:04.000Z",
  "data": {
    "timer": {
      "id": "k7Qm2xPa9Lz3", "label": "Black Friday",
      "deadline": "2026-11-27T22:59:00.000Z", "expired": true,
      "imageUrl": "https://api.timerbeam.com/s/k7Qm2xPa9Lz3.gif", …
    }
  }
}

Deliveries follow Standard Webhooks, so its libraries verify them as they are. Or by hand — check the signature against the raw body, and the timestamp against replays:

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body exactly as received, before any JSON parsing.
export function isFromTimerbeam(headers, rawBody, secret) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // replayed or stale
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest('base64');
  return headers['webhook-signature'].split(' ').some((part) => {
    const signature = part.split(',')[1] ?? '';
    return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  });
}

Answer with any 2xx within 10 seconds. Anything else is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h, then marked failed — the Webhooks page shows every delivery, its answer, and a Retry button. The same webhook-id comes with every retry, so a repeat is easy to ignore. Answer 410 Gone to turn the endpoint off. Endpoints must be public https:// URLs; redirects aren’t followed.

For AI agents

Point an agent at the OpenAPI document — every operation has an operationId, a summary and example requests — and give it a key (a read-only one, to start). The errors say what to change, local deadlines need no offset arithmetic, and Idempotency-Key makes its retries safe. A summary of the whole product for language models is at /llms.txt. Or connect it to the MCP server and skip the HTTP entirely.

MCP server

Timerbeam is also an MCP server, so Claude, Cursor and other agents can use it as a set of tools — “make a 48-hour countdown for the welcome email in our brand colours” just works. It’s the same API underneath: the same key, the same plan limits, the same errors.

URL

https://api.timerbeam.com/mcp

Transport

Streamable HTTP

Auth

OAuth sign-in, or an API key

claude.ai and ChatGPT

Add a custom connector (in claude.ai: Settings → Connectors) with this URL, then sign in to Timerbeam and allow it when asked — no key to copy:

https://api.timerbeam.com/mcp

Claude Code

In a terminal — then run /mcp in Claude Code to sign in. (Or skip the sign-in: add --header "Authorization: Bearer tb_live_…".)

claude mcp add --transport http timerbeam https://api.timerbeam.com/mcp

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "timerbeam": {
      "url": "https://api.timerbeam.com/mcp",
      "headers": { "Authorization": "Bearer tb_live_…" }
    }
  }
}

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "timerbeam": {
      "type": "http",
      "url": "https://api.timerbeam.com/mcp",
      "headers": { "Authorization": "Bearer tb_live_…" }
    }
  }
}

Claude Desktop

In claude_desktop_config.json, through the mcp-remote bridge (needs Node.js):

{
  "mcpServers": {
    "timerbeam": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.timerbeam.com/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer tb_live_…" }
    }
  }
}

Clients that support it sign in with OAuth: you approve the app once on a Timerbeam page, choosing nothing more than “Allow”, and it appears under Connected apps on your API keys page, where you can disconnect it. Anything else sends an API key. A read-only key gives an agent the read tools only in effect — anything that would change a timer is refused.

Reference

Timer fields

The body of POST /api/timers and PATCH /api/timers/{id} (a PATCH sends only what changes):