Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/natureloved/DeadMan-Vault/llms.txt

Use this file to discover all available pages before exploring further.

The /api/notify endpoint is a write-only audit log writer for notification events in the Deadman Vault system. It inserts a row into the Supabase notifications table to record that a specific notification was dispatched to a vault owner or beneficiary. This endpoint does not send emails — actual email delivery is handled by the Resend-backed notification functions (sendWarningEmail, sendGracePeriodEmail, sendClaimReadyEmail) called directly by the keeper sweep and heartbeat flows. Those same flows call this endpoint immediately after sending an email so there is a permanent, queryable record of every notification event.
The keeper uses the notifications table to deduplicate emails — for example, warning emails are only resent if no "warning" notification exists for the vault in the last 24 hours. Calling this endpoint outside of the keeper flow will affect that deduplication window, so it should only be used to record notifications that were genuinely dispatched.

​
Endpoint

POST /api/notify

​
Request Body

​
vaultId
string
required
The UUID of the vault this notification is associated with. Must match an existing vault in the database.
​
type
string
required
The category of notification being recorded. The keeper uses the following values:
ValueMeaning
"warning"Owner warned that the deadline is approaching (~3 days remaining)
"grace_period"Owner alerted that the deadline has passed and the grace period is active
"claim_ready"Beneficiary notified that the vault has triggered and their payout is available
"funds_released"Recorded when funds have been confirmed released to a beneficiary
​
email
string
The email address of the notification recipient. Optional — include when the notification was sent to an email address.
​
address
string
The Stacks address of the notification recipient. Optional — include when the notification is associated with a specific on-chain address (e.g. a beneficiary’s wallet).

​
Behaviour

The endpoint calls addNotification() with the provided fields, inserting a single row into the notifications table. The status field is always set to "sent" — this endpoint has no concept of pending or failed delivery states. If the insert fails (e.g. due to a database connectivity issue), the endpoint returns a 500 error and logs the failure to the server console.

​
Response Fields

​
success
boolean
Always true when the notification row was successfully inserted. No other fields are returned on success.

​
Example Request

curl --request POST \
  --url https://your-app.vercel.app/api/notify \
  --header 'Content-Type: application/json' \
  --data '{
    "vaultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "warning",
    "email": "owner@example.com",
    "address": "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ"
  }'
Recording a beneficiary claim-ready notification (address only): 
curl --request POST \
  --url https://your-app.vercel.app/api/notify \
  --header 'Content-Type: application/json' \
  --data '{
    "vaultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "claim_ready",
    "email": "beneficiary@example.com",
    "address": "SP3FGQ8Z7JY9BWYZ5WM53GR3FO2BKGFNHV1E3XBH"
  }'

​
Example Response

{
  "success": true
}

​
Error Responses

StatusCondition
500The Supabase insert failed — database unreachable, constraint violation, or malformed input
Error responses follow the shape: 
{
  "error": "Failed to notify"
}
A 500 from this endpoint means the audit record was not written. If you are calling this endpoint manually after sending a notification via another channel, a failure here means the keeper’s deduplication logic will not know the notification was sent and may re-send it on the next sweep.

Build docs developers (and LLMs) love

Get started for freeTalk to us