Quickstart
This takes you from nothing to a delivered in-app notification on one machine. It uses the insecure development key, so do not point real data at it.
You need the notify and dagnats binaries (Install).
1. Start the dagnats sidecar
dagnats serveLeave it running. notify expects NATS on nats://127.0.0.1:4222, which is what dagnats serve binds by default.
2. Create a tenant
Everything in notify belongs to a scope: an organization and an environment. bootstrap creates both and mints the first API key.
notify bootstrap -dev -org acme -env development{
"apiKey": "9f2c…",
"orgId": "01J…",
"envId": "01J…"
}The key is shown once; notify stores only a hash. Keep it:
export KEY=9f2c…bootstrap writes to the SQLite file named by -db (default notify.db in the current directory). Run it from the same directory, or pass the same -db, as serve. If you lose the key later, notify rotate-key mints a new one.
3. Start notify
notify serve -dev-dev lets notify start without NOTIFY_MASTER_KEY_HEX by deriving a fixed, publicly known key. Outside development, generate a real one and set it on every command that opens the database:
export NOTIFY_MASTER_KEY_HEX=$(openssl rand -hex 32)notify listens on 127.0.0.1:3000 (-addr). On start it connects to dagnats over NATS, and it exits if it cannot. Check it:
curl -s localhost:3000/healthz
# {"status":"ok","version":"0.0.0-dev"}
curl -s localhost:3000/readyz
# {"status":"ok","dagnats":true,"db":true}4. Create a workflow
A workflow is a trigger identifier and a list of steps. This one puts a message in the subscriber’s in-app inbox.
curl -s -X POST localhost:3000/v1/workflows \
-H "Authorization: ApiKey $KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "Order shipped",
"triggerIdentifier": "order-shipped",
"steps": [{
"stepId": "inbox",
"type": "in_app",
"controlValues": {
"subject": "Hi {{subscriber.firstName}}",
"body": "Order {{payload.orderId}} has shipped."
}
}]
}'The response is 201 with the workflow’s id, triggerIdentifier, name and active. New workflows are active.
5. Trigger it
curl -s -X POST localhost:3000/v1/events/trigger \
-H "Authorization: ApiKey $KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "order-shipped",
"to": {"subscriberId": "user-1", "firstName": "Ada", "email": "ada@example.com"},
"payload": {"orderId": "A-100"}
}'{"acknowledged":true,"status":"processed","transactionId":"01J…"}The to object creates or updates the subscriber, so you do not have to create subscribers first. transactionId identifies this send; supply your own to make the call idempotent.
6. Read the inbox
curl -s "localhost:3000/v1/messages?subscriberId=user-1" \
-H "Authorization: ApiKey $KEY"{
"data": [{
"id": "01J…", "subscriberId": "user-1", "channel": "in_app", "status": "sent",
"subject": "Hi Ada", "content": "Order A-100 has shipped.",
"seen": false, "read": false, "archived": false, "…": "…"
}],
"unreadCount": 1,
"unseenCount": 1
}Message fields are camelCase (id, subject, content); see Messages for the full list.
Delivery is asynchronous: the run executes on the dagnats engine, so the message appears a moment after the trigger returns. See Activity in the console, or GET /v1/notifications, to follow a run.
Where next
- Send through a real channel: Channels shows how to create an email, SMS, push or chat integration.
- Add steps: Workflows lists every step type.
- Let a browser read the inbox without your API key: Subscriber sessions.
- Run it for real: Operations.