Notifications

Compose, send, schedule, and read notifications for one app and environment. These routes use a workspace server API key.

These routes are the public API. Send Authorization: Bearer with a workspace server API key. The key can act on every app in the workspace. A route that names an app uses that app id. environment is development or production.

GET /api/v1/public/apps/{app}/environments/{environment}/notifications

The notifications were listed.

Path

• app — App id in this workspace.
• environment — development or production.

Responses

• 200 NOTIFICATIONS_LISTED — The notifications were listed.
  • page (integer, required)
  • per_page (integer, required)
  • total (integer, required)
• 401 INVALID_API_KEY — The API key is invalid.
• 404 APP_NOT_FOUND — The app could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

POST /api/v1/public/apps/{app}/environments/{environment}/notifications

The notification was accepted.

Path

• app — App id in this workspace.
• environment — development or production.

Body

• title (string, required) — Notification title. Required. At most 200 characters.
• body (string, required) — Notification message. Required. At most 1000 characters.
• url (string, optional) — Optional address opened when the notification is tapped. At most 2048 characters.
• image_url (uri, optional) — Optional image URL. At most 2048 characters.
• data (array of string, optional) — Optional object of up to 20 short keys and simple values.
• alert (boolean, optional) — Whether the notification shows an alert. Defaults to true.
• audience_type (all, segment, subscriber, event, required)
• audience_id (string, optional) — Segment id when audience_type is segment. Event name when audience_type is event.
• subscriber_id (uuid, optional) — Subscriber id. Required when audience_type is subscriber.
• intent (draft, send, schedule, required) — draft, send, or schedule.
• timezone_strategy (optional)
• scheduled_at (date-time, optional) — UTC time. Required when intent is schedule.
• idempotency_key (string, optional) — Optional key, at most 80 characters. The same key in this app and environment returns the notification already accepted.

Responses

• 201 NOTIFICATION_ACCEPTED — The notification was accepted.
  • id (string, required)
  • title (string, required)
  • body (string, required)
  • audience (string, required)
  • audience_type (string, required)
  • targeted (integer, required)
  • delivered (integer, required)
  • failed (integer, required)
  • skipped (integer, required)
  • url (string, required)
  • image_url (string, required)
  • data (object, required)
• 200 NOTIFICATION_ACCEPTED — The notification was accepted.
  • id (string, required)
  • title (string, required)
  • body (string, required)
  • audience (string, required)
  • audience_type (string, required)
  • targeted (integer, required)
  • delivered (integer, required)
  • failed (integer, required)
  • skipped (integer, required)
  • url (string, required)
  • image_url (string, required)
  • data (object, required)
• 401 INVALID_API_KEY — The API key is invalid.
• 404 APP_NOT_FOUND — The app could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

POST /api/v1/public/apps/{app}/environments/{environment}/notifications/images

The image was stored.

Path

• app — App id in this workspace.
• environment — development or production.

Responses

• 201 IMAGE_STORED — The image was stored.
  • url (string, required)
• 401 INVALID_API_KEY — The API key is invalid.
• 404 APP_NOT_FOUND — The app could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

POST /api/v1/public/apps/{app}/environments/{environment}/notifications/preview

The audience was counted.

Path

• app — App id in this workspace.
• environment — development or production.

Body

• audience_type (string, required)
• audience_id (string, optional)
• subscriber_id (uuid, optional)

Responses

• 200 NOTIFICATION_PREVIEWED — The audience was counted.
  • name (string, required)
  • audience (integer, required)
  • reachable (integer, required)
• 401 INVALID_API_KEY — The API key is invalid.
• 404 APP_NOT_FOUND — The app could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

GET /api/v1/public/apps/{app}/environments/{environment}/notifications/recipients

The recipients were listed.

Path

• app — App id in this workspace.
• environment — development or production.

Query

• search (string)

Responses

• 200 RECIPIENTS_LISTED — The recipients were listed.
• 401 INVALID_API_KEY — The API key is invalid.
• 404 APP_NOT_FOUND — The app could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

GET /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}

The notification was found.

Path

• app — App id in this workspace.
• environment — development or production.
• notification — Notification id returned when the notification was accepted.

Responses

• 200 NOTIFICATION_FETCHED — The notification was found.
  • id (string, required)
  • title (string, required)
  • body (string, required)
  • audience (string, required)
  • audience_type (string, required)
  • targeted (integer, required)
  • delivered (integer, required)
  • failed (integer, required)
  • skipped (integer, required)
  • url (string, required)
  • image_url (string, required)
  • data (object, required)
• 401 INVALID_API_KEY — The API key is invalid.
• 404 NOTIFICATION_NOT_FOUND — The notification could not be found.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

POST /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}/cancel

The notification was cancelled.

Path

• app — App id in this workspace.
• environment — development or production.
• notification — Draft or scheduled notification id.

Responses

• 200 NOTIFICATION_CANCELLED — The notification was cancelled.
  • id (string, required)
• 401 INVALID_API_KEY — The API key is invalid.
• 404 NOTIFICATION_NOT_FOUND — The notification could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

GET /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}/outcomes

The outcomes were listed.

Path

• app — App id in this workspace.
• environment — development or production.
• notification — Notification id.

Query

• search (string)
• status (pending, delivered, failed, skipped)
• page (integer)
• per_page (10, 25, 50)

Responses

• 200 OUTCOMES_LISTED — The outcomes were listed.
  • page (integer, required)
  • per_page (integer, required)
  • total (integer, required)
• 401 INVALID_API_KEY — The API key is invalid.
• 404 NOTIFICATION_NOT_FOUND — The notification could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.

POST /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}/send

The notification was sent.

Path

• app — App id in this workspace.
• environment — development or production.
• notification — Draft notification id.

Responses

• 200 NOTIFICATION_SENT — The notification was sent.
• 401 INVALID_API_KEY — The API key is invalid.
• 404 NOTIFICATION_NOT_FOUND — The notification could not be found.
• 422 VALIDATION_FAILED — The request contains invalid fields.
• 429 RATE_LIMIT_EXCEEDED — Too many requests. Please try again later.
• 500 SERVER_ERROR — Something went wrong. Please try again.