Messaging

Transactional email, web push, an in-app inbox and realtime channels. Every message is logged with its delivery status.

Email

curl -X POST https://api.dianthan.com/v1/messages/email \
  -H "X-API-Key: dn_live_…" -H "X-App-Id: app_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "ada@example.com",
    "subject": "Your export is ready",
    "text": "Download it here: https://fieldnotes.app/exports/42",
    "html": "<p>Download it <a href=\"https://fieldnotes.app/exports/42\">here</a>.</p>"
  }'

• text is required (up to 50 KB). html is optional (up to 100 KB). Mail clients that can't show HTML show the text.
• Mail is sent from your app's verified domain. Add the domain and its DNS records in the dashboard first.
• A provider failure returns 502 email_failed, and the attempt is still logged.

GET /v1/messages lists deliveries with recipient, subject, status and error, so you can check whether an email was sent before anyone asks.

To send later or retry automatically, queue an email job instead. See Automation.

Web push

1. Fetch the public key: GET /v1/push/vapid-public-key.
2. In the browser, subscribe with the Push API and send the subscription to POST /v1/push/subscriptions.
3. From your server, notify a user:

curl -X POST https://api.dianthan.com/v1/push/send \
  -H "X-API-Key: dn_live_…" -H "X-App-Id: app_…" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"usr_x81…"}'

Pushes wake the service worker without a payload. The worker then fetches what's new from your app, so message content never passes through push services.

In-app inbox

Each user has a notification list at GET /v1/notifications, with read state. Show it in a menu, mark items read, and use the unread count for a badge.

Realtime channels

Publish from your server:

curl -X POST https://api.dianthan.com/v1/channels/publish \
  -H "X-API-Key: dn_live_…" -H "X-App-Id: app_…" \
  -H "Content-Type: application/json" \
  -d '{"channel":"user:usr_x81…","data":{"type":"export.ready","url":"/exports/42"}}'

Subscribe from the browser with server-sent events:

const events = new EventSource(`/api/live?channel=user:${userId}`); // proxied to /v1/channels/:channel/subscribe
events.onmessage = (e) => render(JSON.parse(e.data));

Channels deliver from server to browser. To send from the browser, call your own API, which publishes.

Preferences

GET /v1/me/notifications and PATCH /v1/me/notifications store which messages a person wants and where. Read them before you send. Dianthan stores the choices, and your code decides how to respect them.

In preview: versioned email templates with variables and previews in the dashboard.