Phase 5 · Available

Notifications

Log and track all outbound guest communications across SMS, email, push, in-app, and WhatsApp channels. Use the Notifications API to record messages sent by your systems, track delivery status, and surface failures for retry.

Live sending + delivery log

POST /v1/notifications creates the record and immediately dispatches the message via the configured provider. The response reflects the actual send status. Use PATCH to write back delivery confirmations from provider webhooks.

Provider configuration

Select the active provider per channel with a single env var. Credentials for the chosen provider must also be set. Missing credentials cause status: failed — the API call itself never fails.

ChannelSelector env varOptions → credentials required

smsSMS_PROVIDER

twilio (default)TWILIO_ACCOUNT_SID · TWILIO_AUTH_TOKEN · TWILIO_FROM_NUMBER

vonageVONAGE_API_KEY · VONAGE_API_SECRET · VONAGE_FROM_NUMBER

plivoPLIVO_AUTH_ID · PLIVO_AUTH_TOKEN · PLIVO_FROM_NUMBER

whatsappWHATSAPP_PROVIDER

twilio (default)TWILIO_ACCOUNT_SID · TWILIO_AUTH_TOKEN · TWILIO_FROM_NUMBER

metaMETA_WHATSAPP_TOKEN · META_WHATSAPP_PHONE_ID

emailEMAIL_PROVIDER

sendgrid (default)SENDGRID_API_KEY · SENDGRID_FROM_EMAIL · SENDGRID_FROM_NAME

mailgunMAILGUN_API_KEY · MAILGUN_DOMAIN · MAILGUN_FROM_EMAIL

aws_sesAWS_ACCESS_KEY_ID · AWS_SECRET_ACCESS_KEY · AWS_SES_REGION · AWS_SES_FROM_EMAIL

pushPUSH_PROVIDER

fcm (default)FCM_SERVER_KEY · FCM_PROJECT_ID

onesignalONESIGNAL_APP_ID · ONESIGNAL_API_KEY

in_app—

built-inNo credentials required — marked sent immediately

The Notification object

idstring

Unique notification ID. Prefixed ntf_.

property_idstring

Property this notification belongs to.

guest_idstring?

Guest this notification was sent to.

reservation_idstring?

Reservation this notification relates to.

channelenum

sms · email · push · in_app · whatsapp

statusenum

queued · sent · delivered · failed · read

typeenum

reservation_confirmation · check_in_reminder · check_out_reminder · request_update · review_request · package_offer · general · alert

recipientstring

Phone number, email address, or device token.

subjectstring?

Email subject line (email channel only).

bodystring

Message body text.

error_messagestring?

Provider error detail when status is failed.

sent_atdatetime?

When the message was dispatched to the provider.

delivered_atdatetime?

When delivery was confirmed.

read_atdatetime?

When the recipient opened the message.

created_atdatetime

ISO 8601 timestamp.

Endpoints

POST/v1/notificationsLog a notification

Record an outbound notification. The initial status defaults to queued — update it as delivery progresses.

Request Body

channelstringrequiredDelivery channel: sms, email, push, in_app, or whatsapp.

recipientstringrequiredPhone, email, or device token.

bodystringrequiredMessage body text.

typestringNotification type. Defaults to general.

subjectstringEmail subject line.

guest_idstringLink to a guest record.

reservation_idstringLink to a reservation record.

cURL

curl -X POST https://api.escapelife.ai/v1/notifications \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "type": "check_in_reminder",
    "recipient": "+1 305-555-0101",
    "body": "Your check-in is tomorrow at 3pm. Reply HELP for assistance.",
    "guest_id": "gst_abc123",
    "reservation_id": "res_xyz456"
  }'

Response

{
  "id": "ntf_a1b2c3d4e5f6",
  "property_id": "pty_xyz",
  "channel": "sms",
  "status": "queued",
  "type": "check_in_reminder",
  "recipient": "+1 305-555-0101",
  "subject": null,
  "body": "Your check-in is tomorrow at 3pm. Reply HELP for assistance.",
  "sent_at": null,
  "delivered_at": null,
  "created_at": "2026-03-16T12:00:00Z"
}

GET/v1/notificationsList notifications

Return the notification log for the property, newest first.

Path / Query Parameters

channelstringFilter by channel.

statusstringFilter by status.

typestringFilter by notification type.

limitintegerMax results (1–200). Default 50.

offsetintegerPagination offset. Default 0.

GET/v1/notifications/summaryNotification summary

Total count, delivery rate, and breakdowns by channel, status, and type.

Response

{
  "total": 312,
  "delivery_rate": 94.2,
  "by_channel": {
    "sms": 142,
    "email": 118,
    "push": 38,
    "in_app": 14
  },
  "by_status": {
    "delivered": 218,
    "read": 76,
    "sent": 12,
    "failed": 6
  },
  "by_type": {
    "check_in_reminder": 98,
    "reservation_confirmation": 84,
    "review_request": 72,
    "request_update": 46,
    "general": 12
  }
}

GET/v1/notifications/{id}Retrieve a notification

Fetch a single notification record by ID.

Path / Query Parameters

idstringrequiredNotification ID (ntf_...).

PATCH/v1/notifications/{id}Update delivery status

Write back the delivery result from your provider webhook — update status, timestamps, and any error detail.

Path / Query Parameters

idstringrequiredNotification ID (ntf_...).

Request Body

statusstringNew status: sent, delivered, failed, or read.

sent_atdatetimeWhen the provider dispatched the message.

delivered_atdatetimeWhen delivery was confirmed.

read_atdatetimeWhen the recipient opened the message.

error_messagestringProvider error detail on failure.

Mark delivered

curl -X PATCH https://api.escapelife.ai/v1/notifications/ntf_a1b2c3d4e5f6 \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "delivered",
    "sent_at": "2026-03-16T12:00:05Z",
    "delivered_at": "2026-03-16T12:00:08Z"
  }'