Trigger event notifications and transactional emails, and inspect their delivery status.

Notifications & Email

The Notifications service has two purposes:

Outbound event notifications — fire arbitrary event_type/payload pairs that get fanned out to your subscribed webhook subscriptions.
Transactional email — send templated emails (account verification, password reset, custom transactional notifications) and inspect their delivery state.

Both produce a queryable delivery log so you can audit what was sent and when.

When to use what

Use case	Endpoint
Fan out an event to multiple of your own URLs	Send notification + webhook subscriptions
Notify your own product when a TryVox event happens	Webhook subscriptions (TryVox publishes built-in events automatically)
Send a transactional email to one recipient	Send email
Audit what was delivered	List notifications / List emails

For SMS or WhatsApp messages, use the Messaging API instead.

Send notification

Publishes an event to all matching webhook subscriptions on the tenant. Subscriptions are filtered by event_type — only those whose events array contains the type are dispatched.

POST /v1/notifications/notifications

Request body

Field	Type	Required	Description
`event_type`	string	yes	Free-form event name (`order.created`, `user.signup`, `custom.foo`, etc.).
`payload`	string	yes	Stringified JSON body to deliver to subscribers. Stored verbatim in the delivery log.

Example

curl -X POST https://api.tryvox.io/v1/notifications/notifications \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "order.created",
    "payload": "{\"order_id\":\"ord_123\",\"total\":4299}"
  }'

Response

202 Accepted:

{
  "id": "1b2c3d4e-5f60-7180-9a2b-3c4d5e6f7a8b",
  "event_type": "order.created",
  "queued_subscriptions": 3
}

Each matching subscription gets its own delivery log entry. Failed deliveries are retried with exponential backoff up to the subscription's max_retries.

List notifications

GET /v1/notifications/notifications

Query parameters

Parameter	Description
`event_type`	Filter to one event type.
`status`	`pending`, `delivered`, `failed`.
`subscription_id`	Filter to one subscription.
`page`	Default: `1`.
`per_page`	Default: `20`, max: `100`.

Example

curl -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  "https://api.tryvox.io/v1/notifications/notifications?status=failed&per_page=50"

Response

200 OK:

{
  "data": [
    {
      "id": "1b2c3d4e-5f60-7180-9a2b-3c4d5e6f7a8b",
      "subscription_id": "8f7a4b2e-91c2-4f3d-9a1e-2c4b6d8f0a1c",
      "event_type": "order.created",
      "payload": "{\"order_id\":\"ord_123\",\"total\":4299}",
      "status": "failed",
      "attempts": 3,
      "last_attempt_at": "2026-04-09T10:35:12Z",
      "last_error": "connection timeout",
      "created_at": "2026-04-09T10:30:00Z"
    }
  ]
}

Get notification

GET /v1/notifications/notifications/{id}

Returns the full delivery log entry. Use this when investigating a single failed delivery — the last_error field tells you why each retry failed.

Send email

POST /v1/notifications/emails

Sends a transactional email through TryVox's email provider. The body is rendered from a registered template — raw HTML/text bodies are not accepted on this endpoint.

Request body

Field	Type	Required	Description
`to_email`	string	yes	Recipient address.
`subject`	string	yes	Email subject.
`template_id`	string	yes	Email template ID (managed in the dashboard).
`template_data`	object	no	String map of substitution variables for the template.

Example

curl -X POST https://api.tryvox.io/v1/notifications/emails \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "to_email": "alex@example.com",
    "subject": "Reset your password",
    "template_id": "tmpl_password_reset",
    "template_data": {
      "first_name": "Alex",
      "reset_link": "https://your-app.com/reset?token=..."
    }
  }'

Response

202 Accepted:

{
  "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "to_email": "alex@example.com",
  "subject": "Reset your password",
  "template_id": "tmpl_password_reset",
  "status": "queued"
}

List emails

GET /v1/notifications/emails

Query parameters

Parameter	Description
`status`	`queued`, `sent`, `delivered`, `bounced`, `failed`.
`to_email`	Filter to one recipient.
`template_id`	Filter to one template.
`page`	Default: `1`.
`per_page`	Default: `20`, max: `100`.

Response

200 OK:

{
  "data": [
    {
      "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "to_email": "alex@example.com",
      "subject": "Reset your password",
      "template_id": "tmpl_password_reset",
      "status": "delivered",
      "sent_at": "2026-04-09T10:30:14Z"
    }
  ]
}

Get email

GET /v1/notifications/emails/{id}

Returns the full email record including delivery status, bounce reason if any, and timestamps for each lifecycle event.

Errors

Status	Code	Reason
400	`VALIDATION_FAILED`	Missing field, malformed JSON
401	`INVALID_CREDENTIALS`	Auth ID / Auth Token bad
404	`NOT_FOUND`	(single-fetch) no record
404	`TEMPLATE_NOT_FOUND`	`template_id` doesn't exist
429	`RATE_LIMITED`	Tenant exceeded send rate; retry after `Retry-After`

Operational notes

Email templates are registered separately in the dashboard. The API only references them by template_id; there is no template CRUD on this surface yet.
Event names are arbitrary, but use a consistent convention (namespace.verb, e.g. order.created). Subscribers filter on the literal string.
Payloads are stored in the delivery log indefinitely. Don't put secrets in them — anyone with the API key can read the log.
No client-side templating. Variable substitution happens on the email provider's side using template_data. Don't pre-render HTML.

Notifications & Email

On this page