The Jounce API

Manage your audience from your own code — subscribers, segments, custom fields, and signed webhooks. Base URL https://api.jounce.com/v1 · machine spec at openapi.json.

Quickstart

Create a key in Jounce under Account → Integrations → API, then:

curl https://api.jounce.com/v1/me \
  -H "Authorization: Bearer jk_live_…"

curl -X POST https://api.jounce.com/v1/subscribers \
  -H "Authorization: Bearer jk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","first_name":"Jane","segment_ids":["SEGMENT_ID"]}'

Authentication

• Bearer — Authorization: Bearer jk_live_… (documented, primary).
• HTTP Basic — key as the username, blank password. Works out of the box with generic HTTP clients and existing integration tooling.
• Keys are account-scoped and come in two scopes: read and full. A read key gets 403 read_only_key on any write.
• Keys are shown once at creation and stored hashed. Revoking a key kills it on the next request.
• Keys are secrets — call the API from your server, never from a browser page.

Conventions

• Errors — proper status codes with one envelope: {"error":{"type","code","message"}}. code is a stable machine string, e.g. invalid_email, disposable_domain, read_only_key, create_limit_reached.
• Rate limits — 120/min per account (batch 20/min), with X-RateLimit-Limit/-Remaining/-Reset on every response and Retry-After on 429. New-subscriber creates cap at 5,000/day — ask support to raise it.
• Pagination — cursor-based: ?limit= (max 100) and the response's next_cursor → ?cursor=. Stable on lists of any size; a page never shifts under you.
• Timestamps — ISO 8601 UTC. Unknown is null, never a fake zero.

Endpoints

Subscribers — how writes behave

POST is an upsert by email (safe to retry). Status is one of subscribed · pending · unsubscribed · bounced · complained.

• An update never changes status. Writing to an unsubscribed contact updates their profile and segments; they stay unsubscribed. The response carries the real status and a mailable flag — read it.
• Suppression wins at birth. Creating an address that previously unsubscribed, bounced, or complained with your account creates it at that status, not subscribed. An address that can't receive mail at all is refused with undeliverable.
• Opt-outs sync in. POST /unsubscribe with any email — even one Jounce hasn't seen — and it's recorded, so a later create is born unsubscribed. Push your other tools' opt-outs into Jounce freely.
• double_optin: true (create only) makes the contact pending and sends your account's confirmation email — author one in Jounce first or the request is refused with no_confirmation_email.
• Attest consent when you have it: optin_ip and optin_timestamp are recorded in the contact's permission evidence.
• Shared inboxes (info@, sales@) are accepted with a role_address warning. Throwaway domains are refused (disposable_domain).
• Custom fields ride as custom_fields — string or boolean values, up to 30 keys per request.

{
  "id": "jane@example.com",
  "email": "jane@example.com",
  "status": "subscribed",
  "source": "api",
  "first_name": "Jane",
  "last_name": "",
  "segments": [{ "id": "SEGMENT_ID", "name": "Customers" }],
  "custom_fields": { "company": "Acme" },
  "consent_at": "2026-07-22T10:00:00.000Z",
  "created_at": "2026-07-22T10:00:00.000Z",
  "updated_at": null
}

Adding a subscriber to a segment can enroll them in any automation that watches that segment — the same engine and safety gates as in-app adds. There is no separate enrolment endpoint; segments are the door.

Webhooks

Register an https endpoint and pick events. Deliveries are signed, retried (5 attempts with backoff over ~6 hours), and an endpoint that fails 10 straight deliveries is switched off — flip disabled back to re-arm it.

Payload: { event_id, event_name, event_time, webhook_id, subscriber | list, segment? }. Bulk imports deliberately do not fire per-row events.

Verify the signature

Every delivery carries Jounce-Signature: t=<unix>,v1=<hmac> — HMAC-SHA256 of t + "." + rawBody with your endpoint's secret (shown once at creation):

import crypto from 'node:crypto'

// header: "t=1721650000,v1=6c2e…"  rawBody: the EXACT request bytes
export function verifyJounceSignature(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false // 5-min replay window
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''))
}

Migrating from another platform?

The request shapes here follow the field names most email APIs already use (first_name, custom_fields, segment_ids, double_optin…), and HTTP Basic auth works as-is — most existing integrations port by swapping the base URL and key. Statuses use Jounce's names, and pagination is cursor-based.

Jounce API v1 · openapi.json · Manage keys in Jounce → Integrations → API