Notifications

The notifications API provides access to the transactional email log. Every email Hydra sends (order confirmations, shipping updates, password resets, etc.) is recorded here with its delivery status, recipient, and associated resource metadata.

Base URL: https://api.hydrajs.dev

Auth: All notification endpoints require a secret key (sk_live_* or sk_test_*).

Endpoints

Method	Path	Auth	Description
GET	/v1/notifications	Secret	List notification log entries
GET	/v1/notifications/{id}	Secret	Get a single notification log entry
POST	/v1/notifications/test	Secret	Send a test email

---

List notifications

GET /v1/notifications

Returns a cursor-paginated list of notification log entries. Supports filtering by type, status, recipient email, and associated resource.

Query parameters

Param	Type	Description
limit	integer	Max results per page (1-250, default 20)
cursor	string	Pagination cursor from a previous response
sort	string	Sort field: created_at (default) or type
order	string	Sort direction: desc (default) or asc
type	string	Filter by notification type (e.g. order_confirmation, shipping_confirmation)
status	string	Filter by delivery status: sent, failed, or skipped
email	string	Filter by recipient email address
resource_type	string	Filter by associated resource: order or customer
resource_id	string	Filter by resource ID (e.g. ord_abc123). Must be used with resource_type

Request

curl "https://api.hydrajs.dev/v1/notifications?resource_type=order&resource_id=ord_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "nlog_abc123",
			"type": "order_confirmation",
			"recipient_email": "jane@example.com",
			"subject": "Your order #1042 has been confirmed",
			"status": "sent",
			"provider_message_id": "msg_abc123",
			"error_message": null,
			"metadata": {
				"order_id": "ord_abc123",
				"order_number": 1042,
				"customer_id": "cus_def456"
			},
			"created_at": "2026-09-01T12:00:00.000Z",
			"updated_at": "2026-09-01T12:00:00.000Z"
		}
	],
	"pagination": {
		"cursor": null,
		"has_more": false,
		"total": 1
	}
}

---

Get a notification

GET /v1/notifications/{id}

Returns a single notification log entry by ID.

Request

curl https://api.hydrajs.dev/v1/notifications/nlog_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "nlog_abc123",
		"type": "shipping_confirmation",
		"recipient_email": "jane@example.com",
		"subject": "Your order #1042 has shipped",
		"status": "sent",
		"provider_message_id": "msg_def456",
		"error_message": null,
		"metadata": {
			"order_id": "ord_abc123",
			"order_number": 1042,
			"customer_id": "cus_def456",
			"fulfillment_id": "ful_ghi789"
		},
		"created_at": "2026-09-02T14:30:00.000Z",
		"updated_at": "2026-09-02T14:30:00.000Z"
	}
}

---

Send test notification

POST /v1/notifications/test

Renders a notification template with sample data and sends it to the specified email. Useful for verifying email provider configuration and template rendering before going live.

Request body

Field	Type	Required	Description
type	string	Yes	Notification type to test (see list below)
email	string	Yes	Email address to send the test to

Notification types

Type	Audience	Description
order_confirmation	Customer	Order placed successfully
order_cancelled	Customer	Order was cancelled
refund_issued	Customer	Refund processed
shipping_confirmation	Customer	Order shipped with tracking
delivery_confirmation	Customer	Package delivered
welcome	Customer	Account created
email_verification	Customer	Verify email address
password_reset	Customer	Password reset link
password_changed	Customer	Password was changed
new_order	Staff	New order received
low_stock	Staff	Inventory below threshold

Request

curl -X POST https://api.hydrajs.dev/v1/notifications/test \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order_confirmation",
    "email": "admin@example.com"
  }'

Response 200

{
	"data": {
		"success": true,
		"message_id": "msg_abc123",
		"error": null
	}
}

---

The notification log object

Field	Type	Description
id	string	Unique ID (prefix: nlog_)
type	string	Notification type (e.g. order_confirmation, new_order)
recipient_email	string	Email address the notification was sent to
subject	string	Email subject line
status	string	Delivery status: sent, failed, or skipped
provider_message_id	string | null	Message ID from the email provider (set on successful send)
error_message	string | null	Error details (set on failure)
metadata	object | null	Associated resource IDs (e.g. order_id, customer_id, fulfillment_id)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp