API Reference

GETPOSTDELETE /employees

Org-admin only. Mint / list / revoke per-employee seats.

POST /api/v1/partner/employees
{ "label": "Dave — macOS console", "daily_send_cap": 200, "external_ref": "okta:dave" }

→ { "ok": true,
    "employee": { "employee_id": "emp_…", "label": "…", "daily_send_cap": 200, "status": "active" },
    "employee_token": "emp_live_…",          ← shown ONCE
    "warning": "Store employee_token securely…" }

DELETE body: { "employee_id": "emp_…" }. GET returns the seat list (no tokens).

POST /messages/send

{
  "to_email": "customer@example.com",
  "body_plain": "Your package was delivered at 2:14 PM.",
  "body_html": "<p><strong>Delivered</strong></p>",
  "priority": "urgent",
  "request_read_ack": true,
  "attachments": [{ "url": "https://…/api/ping/attach?k=…", "mime": "image/jpeg", "filename": "pod.jpg", "size": 48211 }],
  "metadata": { "tracking_number": "1Z999…" }
}

Recipient must already be enrolled (active pairing). Debits 1 partner credit. Returns message_id (partner id) + transport_message_id (inbox id).

POST /messages/batch

Org API key + HMAC only — employee seat tokens are rejected. Max 500 recipients per request · 10 batch req/min/partner. Unenrolled recipients are skipped (counted). Sends run async via a background worker. Merge tags: {{name}} from each row’s merge object.

{
  "batch_name": "fedex_sunday_digest",
  "body_plain": "Hi {{name}}, update on {{tracking}}.",
  "body_html": "<p>Hi {{name}}, …</p>",
  "priority": "normal",
  "recipients": [
    { "to_email": "a@example.com", "merge": { "name": "Ann", "tracking": "1Z…" } },
    { "to_email": "b@example.com", "merge": { "name": "Bob", "tracking": "1Y…" } }
  ]
}
→ { "ok": true, "batch_id": "pbatch_…", "status": "queued", "queued": 2, "skipped": 0 }

POST /campaigns · GET /campaigns/{campaign_id}

Org API key + HMAC only. Named wrapper around the same async batch worker (same 500 / 10-per-min limits). Credits debit once per successful recipient — not twice. Poll GET for sent · failed · skipped · status.

POST /api/v1/partner/campaigns
{
  "campaign_name": "spring_digest",
  "body_plain": "Hi {{name}} — your update.",
  "recipients": [
    { "to_email": "a@example.com", "merge": { "name": "Ann" } }
  ]
}
→ { "ok": true, "campaign_id": "pcamp_…", "batch_id": "pbatch_…", "status": "queued", "queued": 1, "sent": 0 }

GET /api/v1/partner/campaigns/pcamp_…
→ { "ok": true, "status": "completed", "sent": 1, "failed": 0, "skipped": 0 }

GET /messages · /messages/{message_id}

Server-side outbox pull. Query: ?limit=25&cursor=0. Status values: delivered · read · dismissed · acknowledged.

GETPOSTDELETE /webhook

Configure a signed outbound webhook. Org key+HMAC only.

POST /api/v1/partner/webhook
{ "url": "https://your.app/hooks/blasts", "events": ["message.read","message.dismissed","enrollment.confirmed"] }
→ { "ok": true, "webhook": {…}, "webhook_secret": "whsec_…" }   ← shown ONCE

POST { "test": true }   → fires a signed ping event

Verify every delivery:

signed   = `${X-Blasts-Webhook-Timestamp}.${rawBody}`
expected = hex(hmac_sha256(webhook_secret, signed))
assert timingSafeEqual(expected, X-Blasts-Webhook-Signature.replace('sha256=',''))
assert abs(now - timestamp) < 5 minutes

Delivery: one immediate attempt (5s); retries hourly with backoff, max 5, then drop. HTTPS only; no localhost / IP literals (SSRF guard). Dedupe on X-Blasts-Event-Id.

GET /webhook/deliveries

Org API key + HMAC only. Debug log of recent outbound attempts (last 100 kept; newest first). Never returns webhook_secret.

GET /api/v1/partner/webhook/deliveries?limit=50
→ {
  "ok": true,
  "count": 1,
  "deliveries": [
    { "event_id": "evt_…", "type": "ping", "http_status": 200, "ok": true, "attempt": 1, "at": "…", "last_error": null }
  ]
}

Enrollment

• POST /enrollment/links — mint hosted URL → blasts.dev/enroll/…
• GET / POST /enrollment/redeem — public preview + one-time redeem (magic link or paste code; no API key)
• POST /enrollment/confirm — partner server-side confirm (org key + HMAC)
• GET /enrollment/status?email=
• POST /templates/validate — lint HTML without sending
• GET /me — verify credentials / quota