Skip to main content
The Spotzee API uses date-based versions. Pin a version with the Spotzee-Version request header. See API versioning for the full pinning model.

​
2026-09-15

​
Template email headers

Email templates support optional data.customHeaders rows with name and value fields. Add per-contact values in email advanced settings across all editor types. Campaigns, journeys and proofs use the template’s values, and preview and proof requests preserve supplied journey variables. Both the campaign wizard and template details form show compact header rows with names inside empty fields and a minus button in the third column. Failed saves keep your form open so you can correct validation errors. WYSIWYG saves preserve header rows, including literal empty values, and accept supported generated list styles. Template names override matching provider headers without regard to case. An empty or whitespace-only rendered value suppresses the matching provider header; removing the template row restores the provider default. Reserved names and duplicate names prevent saving. Unsafe rendered control characters stop the send before provider submission. Existing templates need no migration. See Custom email headers for configuration, variables and validation rules, or Set up email delivery for provider configuration.

​
Tooling, 2026-04-29 (afternoon)

​
Extended API consolidated onto apix.spotzee.com

Both the Main API and Extended API now serve from the same hostname. Update your client configuration: This is a hard cutover with no overlap. Update your integrations.

​
Extended API conventions aligned with Main API

The Extended API now ships the same wire-level conventions as the Main API:
  • Spotzee-Version header: required to be either 2026-04-28 or omitted (server defaults to current). Echoed on every response.
  • X-Request-Id header: req_<id> on every response. Globally unique per request. Quote it in support tickets.
  • application/problem+json: error responses now use the RFC 7807 media type.
  • OpenAPI 3.1: the published spec is now OpenAPI 3.1.0 (was 3.0.0).
  • Canonical error envelope: {status, code, title, message, error, type, request_id} matches the Main API exactly. The legacy error field is kept as the canonical envelope’s optional mirror until a future major version.

​
2026-04-28

The first publicly-versioned release of the Spotzee API.

​
New surface

  • Project-scoped surface at https://apix.spotzee.com/api/client with sk_ (secret) and pk_ (publishable) keys.
  • Organisation-scoped surface at https://apix.spotzee.com/api/admin with ok_ keys for cross-project administration.

​
New conventions

  • Versioning: Spotzee-Version request header (date-based). Echoed back on every response.
  • Idempotency: Idempotency-Key header on POST and PATCH. 24-hour TTL, scoped per API key. Same key + same body returns the cached response; same key + different body returns 409 idempotency_key_mismatch.
  • Rate limits: per-key sliding window, separate read and write buckets, generous tiers for MCP and agent workloads (x-spotzee-client-type: mcp doubles the base limit).
  • Errors: RFC 7807 application/problem+json envelope with stable string code, title, message, request_id, optional param and errors[] for per-field validation breakdowns.
  • Correlation: every response carries an X-Request-Id header (req_<ULID>). Quote it in support tickets.

​
New endpoints

Public surface for the first time:
  • Users: list, get, upsert (single + batch up to 100), delete. Public name is User.
  • Lists: full CRUD. Static and dynamic flavours; dynamic lists are how you express segments via the API.
  • Subscriptions: opt-in management per channel.
  • Templates: multi-channel template management with preview and proof endpoints.
  • Campaigns: full CRUD plus duplicate, preview, and trigger.
  • Journeys: full CRUD plus trigger. Live status required for entrances.
  • Tags: full CRUD.
  • Events: single + batch ingestion (up to 100 events per call), publishable-key-allowlisted for browser use.
  • Project API keys: manage your own sk_ and pk_ keys.
  • Organisation API keys: manage ok_ keys (admin role required).
  • Webhook endpoints: manage outgoing webhook subscriptions and signing secrets.

​
Migration notes

This is the first dated release, so there’s nothing to migrate from.

​
Tooling, 2026-04-29

These don’t change the API surface but are worth knowing about if you’re building against the spec.

​
Typed JavaScript SDK

The @spotzee/js-sdk package now ships a fully typed client generated from the live OpenAPI 3.1 spec at the /generated subpath. Every operation is exposed as a typed function with inputs, outputs, and the full RFC 7807 error envelope. The hand-written Client / BrowserClient / Spotzee classes for browser tracking are unchanged. The typed surface is purely additive.
Install:

​
Cross-API schema sharing

Cross-cutting types (ErrorResponse, PaginationQuery, Channel, prefixed identifiers) now resolve to the same canonical definitions across the Main API and the Extended API. Client code that handles errors uniformly across both APIs is a single import.

​
Coming soon

  • Autogenerated code samples in curl / JavaScript / Python / Go on every endpoint page.
Subscribe to the changelog page in your reader of choice for future releases.