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.

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.

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.

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 '{
    "recipients": [
      { "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({
    recipients: [{ 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); // "ntsnd_01...", 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={
        'recipients': [{'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": "ntsnd_01...", "recipients": 1, "status": "pending" }

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.

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

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.

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. They are server-side helpers used by first-party platform flows (there is no preset parameter on the send endpoint), so treat the table below as the recommended bundles to assemble in your own request body. Caller-supplied fields always win over a preset's defaults; an omitted channels lets the company config resolve them per category.

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.

Supported Channels

push is APNs/FCM; web_push is VAPID. Per-app channel credentials live in the owner-managed config and are never account-writable.

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.

Read a Recipient's Feed

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

Mark a Row's State

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.

{
  "data": {
    "send_id": "ntsnd_01j9z4f6w8m3qk2c7d5h0abxyz",
    "status": "pending",
    "channels": ["email", "push"],
    "created_at": 1719446400,
    "title": "Your invoice is ready",
    "category": "transactional",
    "type": null,
    "recipients": [
      {
        "recipient_id": "user@example.com",
        "enqueued": true,
        "seen_at": 1719446460,
        "read_at": null,
        "archived_at": null
      }
    ],
    "counts": { "total": 1, "enqueued": 1, "seen": 1, "read": 0, "archived": 0 }
  },
  "meta": { "api_version": "1.2.828", "request_id": "...", "response_ms": 34, "timestamp": 1719446400 }
}

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.

List Account Receipts

Receipts for One Send

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 categories recipients can mute, compliance, and branding.

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,
      "quiet_hours": { "enabled": false, "start": "22:00", "end": "07:00", "tz": "UTC" },
      "coalesce_window_seconds": 30
    },
    "reliability": {
      "dedup_window_seconds": 60,
      "rate_limit_per_recipient_per_minute": 0,
      "digest_frequency": "instant",
      "dlq_threshold": 8
    },
    "history": { "history_ttl_days": 30, "max_rows_per_user": 2000, "receipt_retention_days": 365 },
    "security": {
      "default_confidentiality": "encrypted_reveal",
      "verification_level": "none",
      "reveal_freshness_minutes": 0,
      "recall_window_hours": 24,
      "reply_enabled": false,
      "mandatory_seal_categories": []
    },
    "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 }
    },
    "compliance": { "marketing_suppression": true, "signature_required": {} },
    "branding": { "logo_url": null, "primary_color": null, "sender_name": null, "support_email": null, "locale": "en" }
  },
  "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 }
    }
  }'

Categories & Recipient Preferences

Two tiers decide delivery. The send resolves an offered channel ladder once; fan-out then narrows it per recipient from their stored preferences. Precedence is strict:

• 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.
• 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.
• Application is fail-open: a preferences fault delivers as offered rather than dropping a notification. Preferences apply to recipients addressed by SVID (ing_*); a suppressed recipient gets no row, no delivery, and is not metered.

Security & Billing

Security Properties

• Sealed by default: confidential content is sealed per recipient; transports carry only an opaque pointer.
• Single-use grants: each SparkLink burns on first use, so a leaked pointer cannot be replayed.
• Metadata-only reads: inbox, status, and receipts never echo plaintext or a recipient's raw contact.
• 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

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. 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.

Error Handling

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

{
  "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: