Notifications API

This document provides a comprehensive guide to the Notifications API, allowing you to programmatically send and manage notifications for your users.

Introduction

The Notifications API enables you to deliver timely and relevant messages to your users through various channels, such as push notifications, email, or in-app alerts. This API is designed to be flexible and scalable, supporting a wide range of use cases from marketing campaigns to critical system alerts.

Base URL

All API requests should be made to the following base URL:

https://api.example.com/v1

Authentication

All requests to the Notifications API must be authenticated. Please refer to the Authentication section for details on how to obtain and use API keys or OAuth tokens.

Endpoints

POST /notifications

Sends a new notification to one or more recipients.

Request Body

The request body should be a JSON object with the following properties:

Parameter	Type	Required	Description
recipients	Array of Strings	Yes	A list of user IDs or email addresses to send the notification to.
message	Object	Yes	The content of the notification.
message.title	String	Yes	The title of the notification.
message.body	String	Yes	The main content of the notification. Supports basic Markdown.
message.type	String	No	The type of notification (e.g., 'info', 'warning', 'alert'). Defaults to 'info'.
channel	String	No	The channel to send the notification through (e.g., 'push', 'email', 'sms'). If not specified, the system will use the user's preferred channel or a default.
metadata	Object	No	Optional key-value pairs for additional context (e.g., deep link URL).

Example Request

    POST /v1/notifications
    Content-Type: application/json
    Authorization: Bearer YOUR_ACCESS_TOKEN

    {
      "recipients": ["user123", "user456@example.com"],
      "message": {
        "title": "New Order Confirmation",
        "body": "Your order #12345 has been successfully placed. Thank you for shopping with us!",
        "type": "info"
      },
      "channel": "email",
      "metadata": {
        "order_id": "12345",
        "tracking_url": "https://example.com/track/12345"
      }
    }
        

Example Response (Success)

    HTTP/1.1 202 Accepted
    Content-Type: application/json

    {
      "message_id": "notif_abc123xyz789",
      "status": "queued",
      "recipients_processed": 2
    }
        

Example Response (Error)

    HTTP/1.1 400 Bad Request
    Content-Type: application/json

    {
      "error": {
        "code": "invalid_request",
        "message": "Missing required 'message.title' field."
      }
    }
        

GET /notifications/{notification_id}

Retrieves the status and details of a specific notification.

Parameters

Parameter	Type	Required	Description
notification_id	String	Yes	The unique identifier of the notification.

Example Request

    GET /v1/notifications/notif_abc123xyz789
    Authorization: Bearer YOUR_ACCESS_TOKEN
        

Example Response (Success)

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
      "notification_id": "notif_abc123xyz789",
      "status": "delivered",
      "sent_at": "2023-10-27T10:00:00Z",
      "recipients": [
        {
          "identifier": "user123",
          "status": "delivered"
        },
        {
          "identifier": "user456@example.com",
          "status": "delivered"
        }
      ],
      "message": {
        "title": "New Order Confirmation",
        "body": "Your order #12345 has been successfully placed. Thank you for shopping with us!",
        "type": "info"
      },
      "channel": "email",
      "metadata": {
        "order_id": "12345",
        "tracking_url": "https://example.com/track/12345"
      }
    }
        

Notification Types

The message.type parameter allows you to categorize notifications. Common types include:

• info: General information.
• warning: Important information that may require attention.
• alert: Critical alerts that require immediate action.
• success: Confirmation of a successful operation.

Channels

You can specify the desired delivery channel using the channel parameter. If omitted, the system will attempt to use the user's preferred channel or a default mechanism.

• push: For mobile app push notifications.
• email: For sending notifications via email.
• sms: For sending notifications via SMS.
• in_app: For in-app notifications within your application.