Notify v1

Overview

SparkVault Notify delivers notifications that are verified, sealed, and provable, not plaintext blasts. A notification reaches the right person, proves they read/approved/signed it with a portable receipt, keeps replies encrypted, and stays recallable. Notify is composed from the SparkVault primitives rather than bolted onto them: every send is one sealed Spark behind a single-use SparkLink, opened through an Identity verification ceremony, with Notify owning only transport and orchestration.

  1  SOMETHING HAPPENS IN YOUR SYSTEM
     A payment is flagged. A contract is ready. A login needs approval.
                          │
                          │  sv.products.notify.send()
                          ▼
  2  NOTIFY SEALS IT AND PICKS THE CHANNELS
     One single-use grant per recipient. Every channel carries only
     https://x.sv/<link_code>, never the content. Notify walks each
     person's channels in order and stops at the first one that lands.
         │             │              │               │
         ▼             ▼              ▼               ▼
  3  IT ARRIVES WHERE THEY ALREADY LOOK
     ┌──────────┐ ┌───────────┐ ┌────────────┐ ┌──────────────┐
     │ Push     │ │ Email     │ │ Text       │ │ Your own app │
     │ phone or │ │ a link,   │ │ when it    │ │ the Notify   │
     │ browser  │ │ not the   │ │ cannot     │ │ feed, via    │
     │          │ │ content   │ │ wait       │ │ the SDK      │
     └──────────┘ └───────────┘ └────────────┘ └──────────────┘
                              │
                              ▼
  4  THEY OPEN IT
     tap the link  ──▶  prove who they are  ──▶  the content renders
     any channel,       a passkey, or the        once, then the grant
     the same grant     level you required       is spent
                              │
                              ▼
  5  YOU GET PROOF, NOT A GUESS
     notify.delivered / .signed / .approved / .denied / .replied reach
     your webhook the moment they happen, and each ceremony receipt
     carries an EdDSA proof that verifies against your JWKS.
                              │
                              └──▶  back into your workflow  (step 1)

The Four-Layer Model

Notify never touches crypto directly. Each layer owns one job, so confidential content stays sealed end to end and the transport only ever carries an opaque pointer.

  the message                          what the channels carry
  ───────────                          ────────────────────────
  ┌──────────────────────────────┐
  │ Spark      sealed content    │ ──▶  nothing (never leaves)
  │            TTL, burn rules   │
  ├──────────────────────────────┤
  │ SparkLink  one single-use    │ ──▶  https://x.sv/<link_code>
  │            grant per person  │      (an opaque pointer)
  ├──────────────────────────────┤
  │ Identity   the verification  │ ──▶  EdDSA proof of WHO opened it
  │            ceremony          │
  ├──────────────────────────────┤
  │ Notify     channels, fan-out │ ──▶  the pointer, on every channel
  │            escalation, inbox │      email · sms · push · in_app
  └──────────────────────────────┘

  Notify never touches crypto. Every channel is a dumb pointer carrier.

Base URL & Authentication

All Notify endpoints are served under a single base path. The tenant is taken from your authenticated account token. There is no account ID in the path.

https://api.sparkvault.com/v1/products/notify

Authentication

Every endpoint is account-token authed (a registered user). Pass a session JWT or an API key; both resolve to the calling account, which scopes tenant isolation on every read and write.

Response Envelope

Every success response wraps its payload in a data envelope with a meta sibling carrying the deployed API build version and server timing. The field tables on this page describe the contents of data. Error responses carry an error object with a meta sibling carrying api_version (see Error Handling).

{
  "data": { /* endpoint payload: documented per endpoint below */ },
  "meta": { "api_version": "1.2.828", "request_id": "...", "response_ms": 12, "timestamp": 1719446400 }
}

Quick Start

Send your first sealed notification with a single POST. Notify seals the content for each recipient, mints a single-use SparkLink, and returns a send_id you can poll for delivery status and receipts.

// npm install @sparkvault/sdk-js
import SparkVault from '@sparkvault/sdk-js';
// CommonJS: const { SparkVault } = require('@sparkvault/sdk-js');

const sv = SparkVault.init({
  accountId: process.env.SPARKVAULT_ACCOUNT_ID,   // acc_...
  apiKey: process.env.SPARKVAULT_API_KEY          // sv_live_...
});

const invoiceId = '1043';
const recipient = { id: 'usr_01hq8yv2k3', email: 'user@example.com' };

const result = await sv.products.notify.send({
  // Idempotency key — safe to retry with the same value. See Idempotency below.
  sendId: `invoice-${invoiceId}-${recipient.id}`,
  // BOTH handles: the id gets them the in-app row, the email is what the
  // 'identifier' policy makes them prove and what the email channel delivers to.
  recipients: [{ id: recipient.id, email: recipient.email }],
  title: 'Your invoice is ready',
  category: 'transactional',
  content: {
    payload: `Invoice #${invoiceId} for $129.00 is attached.`,
    contentType: 'text/plain'
  },
  policy: { verificationLevel: 'identifier', interaction: 'view' },
  channels: ['email', 'push']
});

console.log(result.send_id, result.recipients, result.status);
// "invoice-1043-usr_01hq8yv2k3", 1, "pending"

curl -X POST 'https://api.sparkvault.com/v1/products/notify/send' \
  -H 'X-API-Key: sv_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "send_id": "invoice-1043-usr_01hq8yv2k3",
    "recipients": [
      { "id": "usr_01hq8yv2k3", "email": "user@example.com" }
    ],
    "title": "Your invoice is ready",
    "category": "transactional",
    "content": {
      "payload": "Invoice #1043 for $129.00 is attached.",
      "content_type": "text/plain"
    },
    "policy": { "verification_level": "identifier", "interaction": "view" },
    "channels": ["email", "push"]
  }'

const res = await fetch('https://api.sparkvault.com/v1/products/notify/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SPARKVAULT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    send_id: 'invoice-1043-usr_01hq8yv2k3',
    recipients: [{ id: 'usr_01hq8yv2k3', email: 'user@example.com' }],
    title: 'Your invoice is ready',
    category: 'transactional',
    content: {
      payload: 'Invoice #1043 for $129.00 is attached.',
      content_type: 'text/plain'
    },
    policy: { verification_level: 'identifier', interaction: 'view' },
    channels: ['email', 'push']
  })
});

const { data } = await res.json();
console.log(data.send_id, data.recipients, data.status);
// "invoice-1043-usr_01hq8yv2k3", 1, "pending"

import os, requests

res = requests.post(
    'https://api.sparkvault.com/v1/products/notify/send',
    headers={'X-API-Key': os.environ['SPARKVAULT_API_KEY']},
    json={
        'send_id': 'invoice-1043-usr_01hq8yv2k3',
        'recipients': [{'id': 'usr_01hq8yv2k3', 'email': 'user@example.com'}],
        'title': 'Your invoice is ready',
        'category': 'transactional',
        'content': {
            'payload': 'Invoice #1043 for $129.00 is attached.',
            'content_type': 'text/plain'
        },
        'policy': {'verification_level': 'identifier', 'interaction': 'view'},
        'channels': ['email', 'push']
    }
)
res.raise_for_status()
data = res.json()['data']
print(data)
# { "send_id": "invoice-1043-usr_01hq8yv2k3", "recipients": 1, "status": "pending" }

End to End: an approval, start to finish

One file, six steps, no fragments. Configure the category once at deploy time; the rest runs per approval.

import { createHash } from 'node:crypto';
import { createRemoteJWKSet, jwtVerify } from 'jose';

const API = 'https://api.sparkvault.com/v1';
const H = { 'X-API-Key': process.env.SPARKVAULT_API_KEY, 'Content-Type': 'application/json' };
const call = async (method, path, body) => {
  const res = await fetch(`${API}${path}`, { method, headers: H, body: body && JSON.stringify(body) });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json.data;
};

// 1. ONCE, at deploy time. `required: true` puts it on the compliance floor:
//    no recipient mute silences it and its mail carries no unsubscribe.
await call('PUT', '/products/notify/config', {
  categories: {
    wire_approval: { label: 'Wire approvals', description: 'Approve or decline an outgoing wire.', required: true }
  }
});

// 2. Bind the receipt to THIS wire. Same canonical string at send and at verify.
const wire = { id: 'wr_1043', amount: 'USD 25,000.00', payee: 'Northwind Ltd' };
const canonical = JSON.stringify({ wire_id: wire.id, amount: wire.amount, payee: wire.payee });
const actionHash = createHash('sha256').update(canonical).digest('hex');

// 3. Send. send_id is the idempotency key: derived from the wire, never a clock.
const send = await call('POST', '/products/notify/send', {
  send_id: `wire-approval-${wire.id}`,
  recipients: [{ id: approver.userId, email: approver.email }],  // id reaches their inbox, email is what they prove
  title: 'Approve a wire transfer',
  category: 'wire_approval',
  content: { payload: `Approve ${wire.amount} to ${wire.payee}?` },
  policy: { verification_level: 'identifier', interaction: 'approve', action_hash: actionHash },
  channels: ['in_app', 'push', 'email'],
  escalation: { delays: [0, 300, 900] }   // in-app now, push at 5 min, email at 15 min, each only if still unseen
});
console.log(send.send_id, send.recipients, send.status);   // "wire-approval-wr_1043", 1, "pending"

// 4. Poll DELIVERY. This answers "did a transport accept it", never "did a human act".
let status;
do {
  await new Promise((r) => setTimeout(r, 5000));
  status = await call('GET', `/products/notify/sends/${send.send_id}/status`);
} while (status.status === 'pending' || status.status === 'sending');
for (const r of status.recipients) {
  console.log(r.recipient_id, r.state, r.suppressed_reason ?? '', r.channel_outcomes);
}

// 5. Poll the RECEIPT. It appears only once the recipient ANSWERS. The answer is
//    what spends an interactive grant, so this can legitimately stay empty for hours.
let receipts = [], cursor = null, truncated = true;
while (truncated) {
  const page = await call('GET',
    `/products/notify/sends/${send.send_id}/receipts${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ''}`);
  receipts = receipts.concat(page.receipts);
  ({ truncated, cursor } = page);
}

// 6. Verify one, with no SparkVault credential and no SparkVault call.
const JWKS = createRemoteJWKSet(new URL(`https://auth.sparkvault.com/${accountId}/.well-known/jwks.json`));
for (const receipt of receipts) {
  if (!receipt.signed_token) continue;                       // a plain `view` receipt carries none
  const { payload } = await jwtVerify(receipt.signed_token, JWKS, { algorithms: ['EdDSA'], issuer: accountId });
  if (payload.action_hash !== actionHash) throw new Error('This receipt attests a different action');
  console.log(payload.identity, payload.interaction, payload.decision, new Date(payload.iat * 1000));
  // "ada@example.com" "approve" "approved" 2026-08-27T...
}

Sending Notifications

The send endpoint is the primary entry point. It seals + mints one single-use SparkLink per recipient synchronously from the in-memory payload (so nothing unsealed is ever persisted), then writes the send row whose stream drives fan-out and delivery.

  SYNCHRONOUS, inside POST /v1/products/notify/send
  ─────────────────────────────────────────────────────────────────────
   1. Validate        1 to 500 recipients, a required category, and
      │               exactly one source (content or ingot).
   2. Resolve policy  The channel ladder plus its cumulative escalation
      │               delays, from the account config and the per-send
      │               overrides. Stored on the row, read back verbatim.
   3. Seal and mint   One Spark sealed per recipient, one single-use
      │               SparkLink minted for each, from the in-memory
      │               payload. Nothing unsealed is ever persisted.
   4. Write one row   ONE send row, status "pending". Its audience
      │               carries every recipient's pre-minted entry
      │               { recipient_id, sparklink_code, contact }.
      ▼
  ═════════════════════════════════════════════════════════════════════
   THE API RETURNS HERE
   200, data { "send_id": "...", "recipients": 3, "status": "pending" }
   Nothing has been delivered yet. Every step below runs after the
   caller already has their answer.
  ═════════════════════════════════════════════════════════════════════
      │
  ASYNCHRONOUS, driven by the send row's stream
  ─────────────────────────────────────────────────────────────────────
   5. Change stream      The row's insert starts fan-out. No cron, no poll.
      │
   6. Fan-out         200 recipients per invocation. A larger audience
      │               self-continues on a recipient cursor.
   7. Resolve each    Prune the channels this recipient cannot receive,
      │  ladder       then apply their preferences. A suppressed one
      │               gets a terminal row and no delivery.
   8. Inbox rows      One row per recipient, idempotent per
      │               (recipient, send). The inbox feed and the status
      │               endpoint read these rows.
   9. Enqueue step 0  SendMessageBatch, 10 per call, no delay, onto:
      │
      ├──▶ realtime queue    in_app · websocket
      └──▶ standard queue    email · sms · push · 7 more
             │
             ▼
  10. Sender          Stop if seen_at is set or the grant is consumed,
      │               claim the (notification, step), then dispatch
      │               through the channel adapter.
      ▼
  11. Channel adapter The pointer reaches the recipient on that channel.

      Still unseen? The sender enqueues the next channel on its queue
      with its own delay. The ladder stops the moment the recipient is
      seen or the grant is consumed.

import { createHash } from 'node:crypto';

const canonical = JSON.stringify({ wire_id: wire.id, amount: wire.amount, payee: wire.payee });
const actionHash = createHash('sha256').update(canonical).digest('hex');

// REST only: policy.action_hash is not on the SDK send options.
await fetch('https://api.sparkvault.com/v1/products/notify/send', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.SPARKVAULT_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    send_id: `wire-approval-${wire.id}`,
    recipients: [{ id: approver.id, email: approver.email }],
    title: 'Approve a wire transfer',
    category: 'approval',
    content: { payload: `Approve ${wire.amount} to ${wire.payee}?` },
    policy: { verification_level: 'identifier', interaction: 'approve', action_hash: actionHash }
  })
});

{
  "data": {
    "send_id": "ntsnd_01j9z4f6w8m3qk2c7d5h0abxyz",
    "recipients": 1,
    "status": "pending"
  },
  "meta": { "api_version": "1.2.828", "request_id": "...", "response_ms": 412, "timestamp": 1719446400 }
}

Idempotency: always send a send_id

A send is not free to repeat. Retrying without an idempotency key seals a second Spark, mints a second SparkLink per recipient, delivers a duplicate on every channel, and meters a second notification. Supply your own send_id and the retry is a no-op instead: Notify writes the send row under a conditional put keyed on send_id, so the second attempt returns the original send with idempotent: true and fans out nothing.

Derive it from the thing you are notifying about, not from a clock or a random value — a key that changes between attempts is not an idempotency key. invoice-1043-usr_01hq is a good one; Date.now() is not. It must be 1–128 characters of A-Z a-z 0-9 _ . : - and is unique within your account.

// The SAME sendId on every attempt is what makes this safe to retry.
const sendId = `invoice-${invoice.id}-${recipient.userId}`;

async function sendInvoiceNotification(attempt = 0) {
  try {
    return await sv.products.notify.send({
      sendId,
      // A sealed send defaults to verification_level 'identifier', so the
      // recipient needs an address to prove. An id on its own has none.
      recipients: [{ id: recipient.userId, email: recipient.email }],
      title: 'Your invoice is ready',
      category: 'transactional',
      content: { payload: `Invoice #${invoice.id} for ${invoice.total}.` }
    });
  } catch (err) {
    // 429: you exceeded 300 requests this minute — details carries resets_at.
    // Timeout / network fault: the send may well have SUCCEEDED. Never assume it did not;
    // the sendId is what makes retrying that unknown state safe.
    const retryable = ['RATE_LIMIT_EXCEEDED', 'timeout_error', 'network_error'].includes(err.code);
    if (!retryable || attempt >= 4) throw err;

    const retryAfterMs = (err.details?.resets_at)
      ? Math.max(0, err.details.resets_at * 1000 - Date.now())
      : Math.min(30000, 2 ** attempt * 1000);   // exponential backoff, capped

    await new Promise((r) => setTimeout(r, retryAfterMs));
    return sendInvoiceNotification(attempt + 1);
  }
}

const result = await sendInvoiceNotification();
if (result.idempotent) {
  // This exact send already existed. Nothing was re-sealed, re-sent, or re-metered.
}

Delivery Model: Sealed vs Plaintext

Delivery mode is a property of the message's nature, not a runtime flag. There is one send front door; how the content travels depends on whether it is confidential.

                    SEALED (the default)                  PLAINTEXT (opt in)
                    delivery: "sealed"                    delivery: "plaintext"
                    ──────────────────────────────────    ──────────────────────────────────
  the request       content, up to 500 recipients         content only
                    or one Ingot (Ingot sends are 1:1)    text/plain or text/html
                    policy defaults to identifier         up to 50 recipients
                                                          payload at most 16 KiB
                                    │                                     │
                                    ▼                                     ▼
  what is created   a Spark and a single-use SparkLink    nothing. no seal, no grant
                    one per recipient, at accept          the body rides the send row
                    nothing unsealed is ever stored       for at most 7 days
                                    │                                     │
                                    ▼                                     ▼
  what travels      the pointer only                      the body itself
                    https://x.sv/<link_code>              in_app, push, web_push and email
                    on any of the 12 channels             only. any other channel is a 400
                                    │                                     │
                                    ▼                                     ▼
  the recipient     verifies, then the content reveals    reads it. there is no reveal step
                    view, reply, approve or sign          verification_level must be none
                                                          interaction must be view
                                    │                                     │
                                    ▼                                     ▼
  what remains      a signed EdDSA receipt                no receipt
                    recall revokes the grant              recall returns 400

  A confidential category can never be sent in the clear: secure, conversation,
  approval and signature always seal. An account's config can add categories to
  that set, never remove them.

Presets

Presets are five secure-by-default bundles that pair a policy (verification_level × interaction) with a sensible default channel ladder and a display category. There is no preset parameter on the send endpoint: a preset is a merge over the one send contract, applied before the request goes out, producing an ordinary send. Over REST, assemble the bundle yourself from the table below. In the JS SDK, one call does it. Caller-supplied fields always win over a preset's defaults; an omitted channels lets the company config resolve them per category.

// One helper per bundle. Each is `send()` with the preset merged underneath, so
// every send option still applies — and anything you pass wins over the bundle.
await sv.products.notify.sendAlert({
  recipients: [{ id: user.id }],              // plaintext: no seal, so no address needed
  content: { payload: 'Your export finished.' },
  title: 'Export complete'
});

await sv.products.notify.sendSecureMessage({
  sendId: `payslip-${period}-${user.id}`,
  recipients: [{ id: user.id, email: user.email }],   // sealed → needs a verifiable address
  content: { payload: payslipPdfBase64, contentType: 'application/pdf' },
  title: 'Your payslip'
});

await sv.products.notify.sendApproval({
  sendId: `wire-${transfer.id}`,
  recipients: [{ id: approver.id, email: approver.email }],
  content: { payload: `Approve a wire of ${transfer.amount} to ${transfer.payee}?` },
  title: 'Wire approval'
});
// Also: sendConversation(...) and sendSignatureRequest(...)

// Inspect (or adjust) what a preset would send, without sending it:
import { buildNotifyPresetSend, NOTIFY_PRESETS } from '@sparkvault/sdk-js';

const options = buildNotifyPresetSend('approval', {
  recipients: [{ id: approver.id, email: approver.email }],
  content: { payload: '...' },
  policy: { verificationLevel: 'passkey' }   // your field wins over the bundle's default
});
await sv.products.notify.send(options);

await sv.products.notify.sendApproval({
  recipients: [{ id: approver.id, email: approver.email }],
  content: { payload: `Approve a wire of ${transfer.amount}?` },
  policy: { verificationLevel: 'passkey' }   // your field wins over the bundle
});

Channels & Escalation

Every channel is a dumb pointer-carrier behind one provider seam. No channel ever sees plaintext. The durable inbox row is the source of truth; a WebSocket push is only a best-effort realtime nudge.

  Offered ladder, resolved once per send
  ┌───────────┬───────────┬───────────┬───────────┬───────────┐
  │ in_app    │ push      │ web_push  │ email     │ sms       │
  │ 0s        │ no handle │ no handle │ 240s      │ 600s      │
  │           │ pruned    │ pruned    │           │           │
  └───────────┴───────────┴───────────┴───────────┴───────────┘
                             │
  Fan-out prunes every channel this recipient has no endpoint for, then
  recomputes the schedule. The email hop leaves the 240s slot it inherited
  and fires at the configured email_minutes: 2.
                             ▼
  Effective ladder for this recipient
  ───────────────────────────────────
  t = 0s     in_app    enqueued with no delay
     │
  t = 120s   email     realtime_fallback_delay.email_minutes: 2
     │
  t = 600s   sms       realtime_fallback_delay.sms_minutes: 10

  How the chain ends
  ──────────────────
  Before every step       the chain stops if the recipient's row already has
                          seen_at, or if the grant is consumed or recalled
                          (sealed sends only).
  A step out of retries   the next step is scheduled before the message dead
                          letters, and that step is recorded as failed, not
                          retryable.
  The ladder runs out     the recipient settles exactly once, delivered or
                          failed.

  A schedule the caller states on escalation.delays is kept per channel
  instead of recomputed.

Supported Channels

Deliverable to your recipients

Platform-internal (SparkVault's own account only)

push covers Expo, APNs, and FCM device tokens; web_push is VAPID. Every phone channel — sms, voice, whatsapp, rcs — runs one shared guard: E.164 validation, a +1 (North American) country allowlist, the opt-out register, and a per-account volume ceiling. A recipient outside the allowlist skips that channel and escalation advances to the next one; no phone channel is a way around any of the four checks. Per-app channel credentials live in the owner-managed config and are never account-writable.

webhook, slack and teams resolve their destination from SparkVault's own platform credentials, and that destination is reachable only by SparkVault's account. Naming one on a tenant send is accepted with a 200 and then recorded as { "outcome": "skipped", "detail": "no_destination_configured" } for every recipient. Do not put them in a ladder you rely on.

Verified-Seen-Aware Escalation

When escalation_enabled, each step fires only if the prior step's notification is still unseen. Escalation is the next-channel delivery enqueued with a delay; the chain stops the moment the recipient's verified seen_at is recorded, so a recipient who reads the email is never also called.

{
  "channels": ["push", "email", "voice"],
  "escalation": { "delays": [0, 120, 600] }
}

Cumulative per-step delays in seconds: push immediately, email at 2 minutes if still unseen, a voice call at 10 minutes if still unseen. Omit escalation to derive delays from the company config's per-channel realtime_fallback_delay.

Inbox

The inbox is a recipient's per-notification feed, metadata only. Each row carries the SparkLink pointer so the client opens the link to unseal; the plaintext and the recipient's raw contact are never echoed here. A recalled row carries no pointer at all: read recalled and show the recipient that the content is gone, instead of a reveal that no longer opens.

Read a Recipient's Feed

curl 'https://api.sparkvault.com/v1/products/notify/inbox?recipient_id=usr_019e66a4...&state=unread&limit=25' \
  -H 'X-API-Key: sv_live_your_api_key'

Mark a Row's State

Mark All (bulk)

Send Status

The status endpoint is the sender's per-recipient delivery rollup for one send: “who has this reached, and how far did each recipient get?” It is metadata-only: it never returns the SparkLink pointer, the recipient's contact, or any policy internals.

  A recipient's state is DERIVED at read time from their row. Nothing stores it.

  STILL CHANGING. POLL AGAIN.
  ┌────────────────┐
  │ pending        │  Fan-out queued their first step and the ladder has not settled,
  └────────────────┘  or no row exists for them yet.
        ▲
        │  a later fan-out of the same send drives them, clears the marker and
        │  gives the send back the count
  ┌────────────────┐
  │ rate_limited   │  The per-recipient per-minute ceiling skipped them before any
  └────────────────┘  channel ran, and no fan-out has driven them since.

  SETTLED. THIS IS THE ANSWER.
  ┌────────────────┐
  │ delivered      │  One channel's transport accepted the message. It outranks every
  └────────────────┘  other marker on the row.
        │
        │  a hard bounce replaces that outcome with bounced, so the row leaves
        ▼  delivered
  ┌────────────────┐
  │ undeliverable  │  Every attempted channel declined (skipped, not_implemented or
  └────────────────┘  bounced), or fan-out found no channel with a handle for them
                      (suppressed_reason no_channels or unreachable), or the ladder
                      ran out with nothing delivered and nothing recorded.
  ┌────────────────┐
  │ failed         │  A channel exhausted its retries, every attempt is terminal, and
  └────────────────┘  none delivered. Our transport gave up; the address may be fine.
  ┌────────────────┐
  │ suppressed     │  The person chose silence: global_off, category_muted or
  └────────────────┘  all_channels_opted_out stamped before the ladder, or
                      identifier_unsubscribed stamped mid ladder by the sender.

  ── HOW IT ROLLS UP ───────────────────────────────────────────────────────────

  counts partitions the audience exactly:
    pending + delivered + undeliverable + failed + suppressed + rate_limited = total
  enqueued, seen, read and archived are independent markers. They partition nothing.
  settled = every recipient that is neither pending nor delivered.

  The send level state is the FIRST rule that matches:
    1  no recipient_count on the row, or zero recipients  ->  unknown
    2  every recipient delivered                          ->  delivered
    3  every recipient settled, none delivered            ->  failed
    4  every recipient settled, some delivered            ->  partial
    5  some enqueued or settled, some pending             ->  sending
    6  nothing driven yet                                 ->  pending

  GET /products/notify/sends/:sendId/status recomputes the counts from the recipient
  rows; GET /products/notify/sends reads the send row's own counters. Same derivation.

The seven per-recipient states, and what each one asks of you:

{
  "data": {
    "send_id": "ntsnd_01j9z4f6w8m3qk2c7d5h0abxyz",
    "status": "partial",
    "channels": ["email", "push"],
    "created_at": 1719446400,
    "title": "Your invoice is ready",
    "category": "transactional",
    "type": null,
    "recipients": [
      {
        "recipient_id": "usr_01hq8yv2k3",
        "state": "delivered",
        "enqueued": true,
        "seen_at": 1719446460,
        "read_at": null,
        "archived_at": null,
        "suppressed_at": null,
        "suppressed_reason": null,
        "rate_limited_at": null,
        "channel_outcomes": {
          "email": { "outcome": "delivered", "at": 1719446405, "step": 0 },
          "push":  { "outcome": "skipped",   "at": 1719446405, "step": 1 }
        },
        "delivered": true,
        "undeliverable": false,
        "failed": false
      },
      {
        "recipient_id": "usr_01hq8yv2k4",
        "state": "suppressed",
        "enqueued": false,
        "seen_at": null,
        "read_at": null,
        "archived_at": null,
        "suppressed_at": 1719446401,
        "suppressed_reason": "category_muted",
        "rate_limited_at": null,
        "channel_outcomes": {},
        "delivered": false,
        "undeliverable": false,
        "failed": false
      }
    ],
    "counts": {
      "total": 2, "enqueued": 1, "seen": 1, "read": 0, "archived": 0,
      "pending": 0, "delivered": 1, "undeliverable": 0, "failed": 0,
      "suppressed": 1, "rate_limited": 0, "recalled": 0
    }
  },
  "meta": { "api_version": "1.2.828", "request_id": "...", "response_ms": 34, "timestamp": 1719446400 }
}

Send History

Every send you made, newest first. Metadata and counters only: the index this reads projects display fields and delivery counts and not the audience, so this surface cannot leak a recipient's contact, the SparkLink pointer, or a plaintext body. Take the deliberate second step to /sends/:sendId/status for per-recipient detail.

let cursor = null;
do {
  const page = await sv.products.notify.listSends({ limit: 100, cursor });
  for (const send of page.sends) {
    console.log(send.created_at, send.state, send.title, `${send.delivered_count}/${send.recipient_count}`);
  }
  cursor = page.cursor;
} while (cursor);

Recall

A sealed send can be taken back. Recall closes the reveal: it revokes the per-recipient access grants (or destroys the sealed content outright), so a recipient who has not yet opened the pointer never can. Receipts already produced survive — a recall cannot un-prove something that happened.

A whole-audience recall also stops delivery that is still in flight. A large send goes out in waves, and recalling it withdraws the waves that have not gone yet: no further inbox rows, no further notifications, and nothing further billed against your allowance. Recipients the send had not reached settle as recalled on the status endpoint, so the send finishes instead of reporting pending forever, and every recipient who already has a row sees their reveal withdrawn in their feed (recalled: true, no pointer) rather than a tap that dead ends.

A targeted recall (recipient_ids) is narrower on purpose: it takes back the recipients you name and leaves the send going out to everyone else.

curl -X POST 'https://api.sparkvault.com/v1/products/notify/sends/ntsnd_01j9z4.../recall' \
  -H 'X-API-Key: sv_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{ "recipient_ids": ["usr_01hq..."], "mode": "grant" }'

Receipts

A receipt is a portable, JWKS-verifiable record of a verified recipient interacting with a SparkLink: opening it (accessed), signing for it, approving or denying a bound action, or replying. Receipts are written to the account-scope audit log in plaintext (they are designed to be presented as third-party proof without a vault key), carrying the Identity-signed EdDSA token and the action_hash for bound interactions.

  ┌───────────────────────────────────────────────────────────────────────────┐
  │ 1  The recipient opens the pointer                                        │
  │    GET https://x.sv/<link_code>                                           │
  │    The page names the sender and what is being asked.                     │
  └───────────────────────────────────────────────────────────────────────────┘
                       │
                       ▼
  ┌───────────────────────────────────────────────────────────────────────────┐
  │ 2  Identity runs the ceremony at the level the grant requires             │
  │    identifier or passkey. Invites or an interaction floor it at           │
  │    identifier.                                                            │
  └───────────────────────────────────────────────────────────────────────────┘
                       │   A proof that is too weak or too old is not a denial.
                       ▼   The page offers the ceremony again.
  ┌───────────────────────────────────────────────────────────────────────────┐
  │ 3  The content reveals                                                    │
  │    POST https://x.sv/<link_code>                                          │
  │    What this spends depends on the interaction the grant asks for.        │
  └───────────────────────────────────────────────────────────────────────────┘
                       │
        ┌──────────────┴───────────────┐
        ▼                              ▼
  A VIEW GRANT                   AN INTERACTIVE GRANT
  the READ spends it             the ANSWER spends it
  the reveal is the whole        acknowledge, sign, approve,
  ceremony                       decline, or reply

  active becomes consumed        the reveal spends neither the
  at the reveal                  grant nor the content
  the sealed Spark burns         a reload, a second tab, or a
  on read                        failed submit finds the request
  receipt: sparklink_accessed,   still open inside the
  which records the open         verification window
  Notify stops escalating:       Notify keeps escalating until
  the recipient engaged          the answer lands
                                              │
                                              ▼
                               ┌──────────────────────────────────────────────┐
                               │ 4  The answer                                │
                               │    POST https://x.sv/<link_code>/interaction │
                               └──────────────────────────────────────────────┘
                                 the grant is consumed, the EdDSA proof is
                                 signed, the receipt is written
                                 only then does the revealed content burn
                                 receipt: sparklink_signed, sparklink_approved,
                                 sparklink_denied or sparklink_replied,
                                 verifiable against the tenant JWKS
                                              │
                                              ▼
                               ┌──────────────────────────────────────────────┐
                               │ All or nothing                               │
                               │ No receipt, no spend: the grant reopens and  │
                               │ nothing is burned.                           │
                               └──────────────────────────────────────────────┘

List Account Receipts

Receipts for One Send

Both sources produce the same keys: a field only one of them can fill comes back as null on the other, so a consumer never has to know which partition answered to know the shape.

Verifying a receipt

A receipt's signed_token is a compact JWS you can verify yourself, with no SparkVault involvement and no SparkVault credential. That is the point: it is evidence you can hand to an auditor, a counterparty, or a court, and they can check it against a public key we publish.

The JWKS is per tenant: {account_id} is your acc_..., the account that sent the notification. The same key signs Identity verification tokens, so one verification path covers both.

import { createRemoteJWKSet, jwtVerify } from 'jose';
import { createHash } from 'node:crypto';

const JWKS = createRemoteJWKSet(
  new URL(`https://auth.sparkvault.com/${accountId}/.well-known/jwks.json`)
);

// EdDSA only — never let the token choose its own algorithm. The token names its
// own issuer, so pin it: a receipt signed by another tenant must not verify here.
const { payload, protectedHeader } = await jwtVerify(receipt.signed_token, JWKS, {
  algorithms: ['EdDSA'],
  issuer: accountId
});

console.log(protectedHeader.kid, payload.identity, payload.interaction, payload.decision);

// Bind the proof to the thing you care about, or you have only proved a signature exists.
const expectedActionHash = createHash('sha256').update(canonicalDocumentBytes).digest('hex');
if (payload.action_hash !== expectedActionHash) {
  throw new Error('This receipt attests a different action');
}

Company Configuration

An account's effective Notify behavior is the secure-by-default schema deep-merged with the account's stored overrides. The config drives channel resolution, escalation timing, retention, the default sealed-send policy, and the categories recipients can mute.

Read Config

{
  "effective": {
    "delivery": {
      "default_channels": ["in_app", "push", "web_push", "email", "sms"],
      "channel_priority": {},
      "realtime_fallback_delay": { "email_minutes": 2, "sms_minutes": 10, "voice_minutes": 30 },
      "escalation_enabled": true
    },
    "reliability": {
      "rate_limit_per_recipient_per_minute": 60
    },
    "history": { "history_ttl_days": 30, "receipt_retention_days": 365 },
    "security": {
      "verification_level": "identifier",
      "reveal_freshness_minutes": 0,
      "mandatory_seal_categories": []
    },
    "events": {
      "webhook_url": "https://hooks.example.com/sparkvault/notify",
      "secret_set": true
    },
    "categories": {
      "security": { "label": "Security", "description": "Sign-in, password, and account-safety alerts.", "required": true },
      "account": { "label": "Account", "description": "Changes to your account, team, or plan.", "required": true },
      "transactional": { "label": "Transactional", "description": "Receipts, confirmations, and status updates.", "required": false },
      "product": { "label": "Product updates", "description": "New features, tips, and announcements.", "required": false },
      "marketing": { "label": "Promotions", "description": "Offers and promotional messages.", "required": false }
    }
  },
  "overrides": {}
}

Update Config

curl -X PUT 'https://api.sparkvault.com/v1/products/notify/config' \
  -H 'X-API-Key: sv_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "delivery": { "default_channels": ["push", "email"] },
    "categories": {
      "weekly_newsletter": { "label": "Weekly newsletter", "description": "Our weekly roundup.", "required": false }
    }
  }'

Event Webhooks

Without this, the only way to learn that a notification reached someone — or that they signed, approved, denied, or replied to it — is to poll. Configure an events endpoint and Notify pushes those moments to you, signed so you can prove the request came from us.

Configure it

curl -X PUT 'https://api.sparkvault.com/v1/products/notify/config' \
  -H 'X-API-Key: sv_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": {
      "webhook_url": "https://hooks.example.com/sparkvault/notify",
      "secret": "a-long-random-string-you-generate"
    }
  }'

Both fields are optional in a patch, but nothing is sent until both are stored: an unsigned event is not something SparkVault emits.

Verify the signature

Each event arrives as a JSON POST with an X-SparkVault-Signature header carrying the hex HMAC-SHA256 of the raw request body under your secret. Sign the bytes exactly as received — re-serializing parsed JSON will not match.

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

// Capture the RAW body — a re-serialized object will not produce the same digest.
app.post('/sparkvault/notify', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = createHmac('sha256', process.env.SPARKVAULT_NOTIFY_SECRET)
    .update(req.body)
    .digest('hex');
  const received = req.get('X-SparkVault-Signature') || '';

  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(received, 'utf8');
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString('utf8'));
  // Answer fast. Queue the work; do not process inline.
  res.sendStatus(200);
  queue.push(event);
});

Event types

Seven types, all in one notify. namespace. Anything else is not an event SparkVault emits.

* send_id rides an interaction event only when the grant knows which send minted it — a standalone SparkLink has no send. A plain view emits no event: opening a sealed message is recorded as a receipt, not pushed. Poll /products/notify/receipts for opens.

Optional fields are omitted when absent rather than sent as null, so presence is a usable signal. An event body never carries sealed content, the SparkLink grant code, or the recipient's raw contact.

{
  "event_id": "nev_01j9z4f6w8m3qk2c7d5h0abxyz",
  "type": "notify.approved",
  "account_id": "acc_01hq...",
  "occurred_at": 1719446512,
  "send_id": "invoice-1043-usr_01hq8yv2k3",
  "link_code_hash": "9f2c1a...",
  "interaction": "approve",
  "decision": "approved"
}

{
  "event_id": "nev_01j9z4f6w8m3qk2c7d5h0abcde",
  "type": "notify.delivered",
  "account_id": "acc_01hq...",
  "occurred_at": 1719446405,
  "send_id": "invoice-1043-usr_01hq8yv2k3",
  "recipient_id": "usr_01hq8yv2k3"
}

Categories & Recipient Preferences

Two tiers decide delivery. The send resolves an offered channel ladder once; fan-out then narrows it per recipient — first by what they can actually receive, then by what they asked for. Precedence is strict:

• Capability comes first, before any preference and before the compliance floor: a channel this recipient has no way to receive on is pruned from their ladder, in three sweeps — device channels (push, web_push) with no registered handle, inbox channels (in_app, websocket) for a recipient with no first-party SparkVault inbox, and identifier channels (email, sms, voice, whatsapp, rcs) whose handle the send never carried. A pruned step does not sit in the ladder burning its delay: the surviving channels are re-based so they fire at their configured cadence rather than waiting behind a hop that could never land. Pruning is fail-open — an absent or malformed contact prunes nothing and the dead channel simply skips at dispatch.
• Categories are the single source for what a send is classified as and what a recipient can mute. Each entry is { label, description, required }; required: true is the compliance floor and can never be muted. security is platform-reserved and always required; the seeded preset categories secure, approval, and signature also ship required (see Presets).
• Recipient preferences are per person, per site ({ global_off, muted_categories, channels }), managed on the recipient's auth.sv per-site page. A mandatory category is delivered regardless of any preference.
• Preferences belong to the PERSON, not to however a send addressed them. They are keyed by the recipient's SparkVault identity (SVID), so a recipient you address by email or phone is resolved to their SVID through the Identity directory and their stored mutes are applied. You do not have to know someone's SVID for their unsubscribe to be honoured — email is the form of address an unsubscribing recipient is most likely to have been reached at, and it is honoured. A recipient with no SparkVault identity resolves to none and keeps identifier-level suppression (unsubscribe / bounce suppression).
• Application is fail-open: a preferences fault, or a directory lookup that faults, delivers as offered rather than dropping a notification. A suppressed or rate-limited recipient still gets a terminal row — carrying suppressed_at or rate_limited_at and an empty ladder — so a status read can tell an opt-out from a delivery still in flight. They are never driven and never metered.

Suppressions & Unsubscribe

An opt-out is not a one-way door. These two endpoints let you see who opted out of your mail and put someone back on the list once they ask — without a support ticket about somebody else's recipients.

List your suppressions

let cursor = null;
do {
  const params = new URLSearchParams({ limit: '100' });
  if (cursor) params.set('cursor', cursor);

  const res = await fetch(
    `https://api.sparkvault.com/v1/products/notify/suppressions?${params}`,
    { headers: { 'X-API-Key': process.env.SPARKVAULT_API_KEY } }
  );
  const { data } = await res.json();

  for (const row of data.suppressions) {
    console.log(row.email, row.type, row.created_at);
  }
  cursor = data.cursor;   // loop until it comes back null
} while (cursor);

The cursor is the same opaque contract /sends and /receipts use: it carries the whole page pointer, so never assemble one from a field on a row, and never treat a short page as the end — cursor being null is the only end-of-list signal.

Clear one suppression

The unsubscribe endpoint

Every non-critical email SparkVault sends on your behalf carries an unsubscribe URL, in the footer and in the RFC 8058 headers. It is a public endpoint with two verbs, and the difference is load-bearing:

One-click headers

Outgoing non-critical mail carries both RFC 8058 headers, pointing at the same endpoint and the same signed token as the visible footer link:

List-Unsubscribe: <https://api.sparkvault.com/v1/unsubscribe?token=...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe alone is a 20-year-old convention that clients render as a link; the -Post companion is what makes Gmail and Outlook show their own Unsubscribe control and honour it without a click-through — which is what keeps a frustrated recipient from pressing “Report spam” instead. Both providers have required the pair on bulk mail since February 2024, and a complaint costs the whole platform's sending reputation, not just yours.

Security & Billing

Security Properties

• Sealed by default: confidential content is sealed per recipient; transports carry only an opaque pointer.
• Single-use grants: each SparkLink is spent once, so a leaked pointer cannot be replayed. For a view-only grant that is the first open. For an interactive grant (acknowledge / sign / approve / reply) the answer spends it, not the reveal — reading an approval request is not answering it, so a reload or a restored tab cannot lock the recipient out of a request they have not yet responded to.
• Metadata-only reads: inbox, status, send history, and receipts never carry sealed content. What they do carry about a person is bounded to what you already hold — the exact guarantee is spelled out below.
• Tenant isolation: a cross-tenant send or notification is reported identically to one that never existed.
• Atomic cleanup: a partial or failed send hard-recalls every grant it minted: no orphaned sealed content.
• Provable interactions: receipts are portable, JWKS-verifiable EdDSA proofs that survive recall and expiry.

Billing

Notify is a subscription product: sending requires an active Notify tier (a monthly notification allowance, purchased from the console's Billing page). Without one, POST /products/notify/send returns 403 NOTIFY_SUBSCRIPTION_REQUIRED; every read surface (inbox, status, receipts, config) stays open. A notification is metered as one recipient × one logical notification: a fan-out to N channels still counts as one, idempotent on the send id, and the allowance resets monthly. The composed Spark + SparkLink + Identity ceremony is included in the Notify unit (it is not double-charged on the standalone usage ledger). Metering is asynchronous and aggregated, with an advisory soft cap that warns and allows overage rather than hard-dropping mid-broadcast; your current cycle's usage rides the notify block of GET /v1/billing/subscription.

Rate Limits

Two independent limits apply, and they fail in completely different ways. One rejects your API call; the other silently drops a recipient. Know both.

1. The account request limit — 300 requests per minute

Every authenticated call to any SparkVault endpoint, Notify included, draws from one account-wide budget of 300 requests per minute in fixed 60-second windows. A single send counts as one request no matter how many recipients it carries, so a 500-recipient fan-out costs the same as a one-recipient one.

Your position in the current window rides on meta.quota of every authenticated response as { limit, used, remaining, resets_at }, so you can back off before you are refused. Exceeding it returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header (seconds until the window resets) and details of { limit, used, resets_at } (resets_at is Unix epoch seconds). Retry with the same send_id and the retry is free. This limiter fails closed: if its own store is unreachable, calls are refused with a 429 rather than let through unmetered.

2. The per-recipient delivery ceiling — 60 per recipient per minute

Separately, Notify caps how many notifications one recipient can be delivered per minute. It defaults to 60, is configurable through reliability.rate_limit_per_recipient_per_minute (integer 1–600), and cannot be disabled — it is the backstop that stops a loop in your code from turning into a notification flood for one person.

This one is enforced at fan-out, not at the API boundary, which is the part that surprises people:

• Your POST /send still returns 200. There is no error, no warning field, and no code to catch.
• An over-limit recipient is dropped from the fan-out. They get no inbox row and no delivery.
• On /sends/:sendId/status that recipient reads enqueued: false with an empty channel_outcomes — the same shape as a recipient suppressed by their own preferences.
• If the counter store itself fails, this check fails open: the notification is delivered rather than lost.

So a 200 from the send endpoint means “accepted”, never “everyone will receive it”. If per-recipient delivery matters, read the status endpoint rather than trusting the send response.

3. The recipient-side link ceilings — 120 per hour each

These apply to your recipient, not to your backend. Three independent hourly buckets, all 120:

Exceeding one returns 429 RATE_LIMIT_EXCEEDED to the recipient with details of { limit, used, resets_at }, where resets_at is the top of the next hour.

It exists because an interactive grant's reveal is deliberately repeatable — the answer spends it, not the read, which is what lets a reload find the request still there. That same property would make an unbounded reveal an amplifier: every open resolves the proof through Identity and writes an access receipt, so anyone holding a live link could inflate your receipt partition by reloading. A real recipient opens a link a handful of times; this bounds the rest, and it is not a limit an ordinary recipient will meet.

See Rate Limiting on the API overview page for the account limit across every product.

Error Handling

Errors return a stable shape. Validation errors name the offending field; tenant-isolation failures are deliberately indistinguishable from a missing resource.

Silent failures — the ones that return 200

Every row below is a successful API call. Read /sends/:sendId/status, never the send response.

Error codes

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Provide exactly one content source: content OR ingot",
    "details": null
  },
  "meta": { "api_version": "1.2.828" }
}

Related

Notify builds directly on the SparkVault primitives. Explore the layers it composes: