Reggiee API

Authentication

Generate a key in Settings → API Keys. Each key belongs to a single brand and is shown once — store it securely. Send it as a Bearer token on every request. Keys can be scoped; a key with no scopes has full access.

curl https://reggi.ee/api/v1/contacts \
  -H "Authorization: Bearer rk_live_your_key_here"

Creating resources & idempotency

POST requests accept JSON. Pass an Idempotency-Key header to safely retry create requests — a repeated key replays the original response instead of creating a duplicate.

curl -X POST https://reggi.ee/api/v1/contacts \
  -H "Authorization: Bearer rk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7e1d..." \
  -d '{ "email": "jane@example.com", "first_name": "Jane", "tags": ["vip"] }'

Responses & errors

Successful responses wrap the payload in a data field; list endpoints add a meta object. Errors use a consistent envelope with an HTTP status, machine-readable code, and human message.

{ "error": true, "status": 403, "code": "insufficient_scope",
  "message": "This API key is missing the required scope: contacts:write" }

Pagination

List endpoints use page and per_page (default 25, max 100) and return meta.total, meta.page, meta.per_page and meta.total_pages. For full exports use the cursor-based /exports/contacts endpoint.

Rate limits

Each key is limited to 60 requests/minute by default. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns 429 with a Retry-After header.

Webhooks

Register endpoints under /webhooks (or in the dashboard) and subscribe to events such as contact.created, campaign.sent, message.delivered and registration.created. Each delivery is signed with your endpoint secret in the X-Reggiee-Signature header (t=<timestamp>,sha256=<hmac>). Verify it before trusting the payload:

import crypto from "node:crypto";

// X-Reggiee-Signature: t=1719240000,sha256=abc123...
export function verify(secret, header, rawBody) {
  const [tPart, sigPart] = header.split(",");
  const t = tPart.split("=")[1];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const provided = sigPart.split("=")[1];
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

Failed deliveries retry with exponential backoff (1m, 5m, 30m, 2h) up to 5 attempts. Inspect the delivery log per endpoint via /webhooks/{id}/deliveries.