🚀 Send Notifications

Prerequisite

A NotificationAPI account - sign up for free
A configured notification in the dashboard

Overview

NotificationAPI supports two methods for sending notifications:

Using templates created in the dashboard and passing dynamic parameters.
Passing content directly in your request (no templates). This guide defaults to direct content in the examples below.

If you want to manage templates in our visual template editor, see the Server reference for sending notifications using templates and check out our Templating documentation to learn more about using templates.

Your team, even non-technical members, can use our dashboard to configure and design your standard notifications without any coding knowledge. For example, they would configure an alert to go over email and completely design its content, subject, etc.

Then, through our SDKs or API, your back-end lets us know when to send this notification to a user. We then take care of the rest.

Let’s learn…

Step 1: Setup the SDK

Install the node package using one of the following package managers:

npm install notificationapi-node-server-sdk

yarn add notificationapi-node-server-sdk

pnpm add notificationapi-node-server-sdk

pip install notificationapi_python_server_sdk

composer require notificationapi/notificationapi-php-server-sdk

go get github.com/notificationapi-com/notificationapi-go-server-sdk

Install the package:

dotnet add package NotificationAPI --version 0.5.0

Add the following dependency to your Maven project:

<dependency>
    <groupId>com.notificationapi</groupId>
    <artifactId>notificationapi-java-server-sdk</artifactId>
    <version>0.2.0</version>
</dependency>

For optimal functionality, you’ll also need the following dependencies:

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.14</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>

# Create the following class in your application

require 'net/http'
require 'json'
require 'base64'
require 'openssl'

class NotificationAPI
  def initialize(client_id, client_secret)
    # if in the CA region, use 'https://api.ca.notificationapi.com'
    # if in the EU region, use 'https://api.eu.notificationapi.com'
    @base_url = 'https://api.notificationapi.com'
    @client_id = client_id
    @auth_token = Base64.strict_encode64("#{client_id}:#{client_secret}")
    # if in the CA region, use 'api.ca.notificationapi.com'
    # if in the EU region, use 'api.eu.notificationapi.com'
    @http_client = Net::HTTP.new('api.notificationapi.com', 443)
    @http_client.use_ssl = true
  end

  def send(request)
    payload = request.to_json
    response = @http_client.post(
      "/#{@client_id}/sender",
      payload,
      {
        'Content-Type' => 'application/json',
        'Authorization' => "Basic #{@auth_token}"
      }
    )
    response.body
  end

  def retract(request)
    payload = request.to_json
    response = @http_client.post(
      "/#{@client_id}/sender/retract",
      payload,
      {
        'Content-Type' => 'application/json',
        'Authorization' => "Basic #{@auth_token}"
      }
    )
    response.body
  end

  def identify_user(user_id, user_data)
    digest = OpenSSL::Digest::SHA256.new
    hmac = OpenSSL::HMAC.digest(digest, @client_secret, user_id)
    hashed_user_id = Base64.strict_encode64(hmac)
    custom_auth = Base64.strict_encode64("#{@client_id}:#{user_id}:#{hashed_user_id}")

    send_request('POST', "users/#{URI.escape(user_id)}", user_data, custom_auth)
  end

  def create_sub_notification(notification_id, sub_notification_id, title)
    payload = { title: title }
    send_request('PUT', "notifications/#{notification_id}/subNotifications/#{sub_notification_id}", payload)
  end

  def delete_sub_notification(notification_id, sub_notification_id)
    send_request('DELETE', "notifications/#{notification_id}/subNotifications/#{sub_notification_id}")
  end

  def update_schedule(tracking_id, scheduleUpdate)
    send_request('PATCH', "notifications/#{tracking_id}", scheduleUpdate)
  end

  def delete_schedule(tracking_id)
    send_request('DELETE', "notifications/#{tracking_id}")
  end

  def set_user_preferences(user_id, user_preferences)
    send_request('POST', "user_preferences/#{user_id}", user_preferences)
  end

  private

  def send_request(method, uri, data = {}, auth = "Basic #{@auth_token}")
    payload = data.to_json
    response = @http_client.send_request(
      method,
      "/#{@client_id}/#{uri}",
      payload,
      {
        'Content-Type' => 'application/json',
        'Authorization' => auth
      }
    )
    response.body
  end

end

Step 2: Send the Notification

Our send function or POST /sender API call takes a JSON payload that specifies which notification to send and to whom. You can either:

Pass the content directly (shown below) via channel overrides like email, sms, etc. or
Use dashboard templates with dynamic parameters. See the Server reference for more details.

INFO

You can get your clientId and clientSecret from here.

// import/require:
import notificationapi from 'notificationapi-node-server-sdk';

// const notificationapi = require('notificationapi-node-server-sdk').default

// initialize notificationapi (default US region)
// if in the CA region, add 'https://api.ca.notificationapi.com' after CLIENT_SECRET
// if in the EU region, add 'https://api.eu.notificationapi.com' after CLIENT_SECRET
notificationapi.init('CLIENT_ID', 'CLIENT_SECRET');

notificationapi
  .send({
    // The ID of the notification you wish to send. You can find this
    // value from the dashboard.
    type: 'order_tracking',
    to: {
      id: 'user123',
      email: 'user@example.com',
      number: '+15005550006' // Replace with format [+][country code][area code][local number]
    },
    email: {
      subject: 'Hello',
      html: '<h1>Hello, world!</h1>'
    },
    sms: {
      message: 'Hello, world!'
    },
    inapp: {
      title: 'Hello',
      url: 'https://example.com',
      image: 'https://example.com/image.png'
    },
    mobile_push: {
      title: 'Hello',
      message: 'Hello, world!'
    },
    web_push: {
      title: 'Hello',
      message: 'Hello, world!',
      icon: 'https://example.com/icon.png',
      url: 'https://example.com'
    },
    call: {
      message: 'This is a test call from NotificationAPI.'
    },
    slack: {
      text: 'Hello, world!'
    }
  })
  .then((res) => console.log(res.data));

# import
import asyncio
from notificationapi_python_server_sdk import (notificationapi)

# initialize notificationapi (default US region)
# if in the CA region, add 'https://api.ca.notificationapi.com' after CLIENT_SECRET
# if in the EU region, add 'https://api.eu.notificationapi.com' after CLIENT_SECRET
notificationapi.init("CLIENT_ID", "CLIENT_SECRET")

# send
async def send_notification():
  await notificationapi.send(
    {
      "type": "order_tracking",
      "to": {
          "id": "spongebob.squarepants",
          "email": "spongebob@squarepants.com",
          "number": "+15005550006"
      },
      "email": {
          "subject": "Hello",
          "html": "<h1>Hello, world!</h1>",
      },
      "sms": {
        "message": "Hello, world!"
      },
      "inapp": {
        "title": "Hello",
        "url": "https://example.com",
        "image": "https://example.com/image.png"
      },
      "mobile_push": {
        "title": "Hello",
        "message": "Hello, world!"
      },
      "web_push": {
        "title": "Hello",
        "message": "Hello, world!",
        "icon": "https://example.com/icon.png",
        "url": "https://example.com"
      },
      "call": {
        "message": "This is a test call from NotificationAPI."
      },
      "slack": {
        "text": "Hello, world!"
      }
    }
  )

# Run the async function
asyncio.run(send_notification())

# import
use NotificationAPI\NotificationAPI;

# init
# if in the CA Region, add 'https://api.ca.notificationapi.com' after Client Secret
# if in the EU Region, add 'https://api.eu.notificationapi.com' after Client Secret
$notificationapi = new NotificationAPI('CLIENT_ID', 'CLIENT_SECRET');

# send
$notificationapi->send([
    #The ID of the notification you wish to send. You can find this
    #value from the dashboard.
    "type" => "order_tracking",
    # The user to send the notification to.
    "to" => [
        "id" => "spongebob.squarepants",
        "email" => "spongebob@squarepants.com",   # required for email notifications
        "number" => "+15005550006" # optional phone number required to send SMS notifications
    ],
    "email" => [
        "subject" => "Hello",
        "html" => "<h1>Hello, world!</h1>",
    ],
    "sms" => [
        "message" => "Hello, world!"
    ],
    "inapp" => [
        "title" => "Hello",
        "url" => "https://example.com",
        "image" => "https://example.com/image.png"
    ],
    "mobile_push" => [
        "title" => "Hello",
        "message" => "Hello, world!"
    ],
    "web_push" => [
        "title" => "Hello",
        "message" => "Hello, world!",
        "icon" => "https://example.com/icon.png",
        "url" => "https://example.com"
    ],
    "call" => [
        "message" => "This is a test call from NotificationAPI."
    ],
    "slack" => [
        "text" => "Hello, world!"
    ]
]);

package main

// import
import (
  notificationapi "github.com/notificationapi-com/notificationapi-go-server-sdk"
  "encoding/json"
)

func main() {
  // init (US region)
  // if in CA Region, replace API URL with 'https://api.ca.notificationapi.com'
  // if in EU Region, replace API URL with 'https://api.eu.notificationapi.com'
  notificationapi.Init("CLIENT_ID", "CLIENT_SECRET", "https://api.notificationapi.com")

  // parameters is to pass dynamic values into the notification design.
  parameters := make(map[string]interface{})
  parameters["item"] = "Krabby Patty Burger"
  parameters["address"] = "124 Conch Street"
  parameters["orderId"] = "1234567890"

  notificationapi.Send(
    notificationapi.SendRequest{
      // The ID of the notification you wish to send. You can find this
      // value from the dashboard.
      Type: "order_tracking",
      // The user to send the notification to.
      To: notificationapi.User{
        Id:     "spongebob.squarepants",
        Email:  "spongebob@squarepants.com",
        Number: "+15005550006" // Optional phone number required to send SMS notifications
      },
      Email: map[string]interface{}{
        "subject":     "Hello",
        "html":        "<h1>Hello, world!</h1>",
      },
      SMS: map[string]interface{}{
        "message": "Hello, world!",
      },
      InApp: map[string]interface{}{
        "title": "Hello",
        "url":   "https://example.com",
        "image": "https://example.com/image.png",
      },
      MobilePush: map[string]interface{}{
        "title":   "Hello",
        "message": "Hello, world!",
      },
      WebPush: map[string]interface{}{
        "title":   "Hello",
        "message": "Hello, world!",
        "icon":    "https://example.com/icon.png",
        "url":     "https://example.com",
      },
      Slack: map[string]interface{}{
        "text": "Hello, world!",
      },
    },
  )
}

//import
using NotificationApi.Server;
using NotificationApi.Server.Models;

// initialize notificationapi (default US region)
// if in the CA region, add 'https://api.ca.notificationapi.com' after boolean argument
// if in the EU region, add 'https://api.eu.notificationapi.com' after boolean argument
var notificationApi = new NotificationApiServer("CLIENT_ID", "CLIENT_SECRET", false);

//send
var user = new NotificationUser("spongebob.squarepants")
{
    Email = "spongebob@squarepants.com",
    TelephoneNumber = "+15005550006"
};

await notificationApi.Send(new SendNotificationData("order_tracking", user)
{
    Email = new Dictionary<string, object>
    {
        { "subject", "Hello" },
        { "html", "<h1>Hello, world!</h1>" },
    },
    SMS = new Dictionary<string, object>
    {
        { "message", "Hello, world!" }
    },
    InApp = new Dictionary<string, object>
    {
        { "title", "Hello" },
        { "url", "https://example.com" },
        { "image", "https://example.com/image.png" }
    },
    MobilePush = new Dictionary<string, object>
    {
        { "title", "Hello" },
        { "message", "Hello, world!" }
    },
    WebPush = new Dictionary<string, object>
    {
        { "title", "Hello" },
        { "message", "Hello, world!" },
        { "icon", "https://example.com/icon.png" },
        { "url", "https://example.com" }
    },
    Slack = new Dictionary<string, object>
    {
        { "text", "Hello, world!" }
    }
});

// import
import com.notificationapi.NotificationApi;
import com.notificationapi.model.NotificationRequest;
import com.notificationapi.model.User;
import java.util.HashMap;
import java.util.Map;

// Initialize NotificationAPI (default US region)
// If in the CA region, use the third parameter: "https://api.ca.notificationapi.com"
// If in the EU region, use the third parameter: "https://api.eu.notificationapi.com"
NotificationApi api = new NotificationApi("CLIENT_ID", "CLIENT_SECRET", "https://api.notificationapi.com");

// Create user
User user = new User("spongebob.squarepants")
    .setEmail("spongebob@squarepants.com") // required for email notifications
    .setNumber("+15005550006"); // optional phone number required to send SMS notifications

// Create and send notification request
NotificationRequest request = new NotificationRequest("order_tracking", user)
    .setEmail(new HashMap<String, Object>() {{
        put("subject", "Hello");
        put("html", "<h1>Hello, world!</h1>");
    }})
    .setSMS(new HashMap<String, Object>() {{
        put("message", "Hello, world!");
    }})
    .setInApp(new HashMap<String, Object>() {{
        put("title", "Hello");
        put("url", "https://example.com");
        put("image", "https://example.com/image.png");
    }})
    .setWebPush(new HashMap<String, Object>() {{
        put("title", "Hello");
        put("message", "Hello, world!");
        put("icon", "https://example.com/icon.png");
        put("url", "https://example.com");
    }})
    .setMobilePush(new HashMap<String, Object>() {{
        put("title", "Hello");
        put("message", "Hello, world!");
    }})
    .setSlack(new HashMap<String, Object>() {{
        put("text", "Hello, world!");
    }});

String response = api.send(request);

# require:
require './NotificationAPI'

# initialize notificationapi (default US region)
# if in the CA region, add 'https://api.ca.notificationapi.com' after CLIENT_SECRET
# if in the EU region, add 'https://api.eu.notificationapi.com' after CLIENT_SECRET
notificationapi = NotificationAPI.new("CLIENT_ID", "CLIENT_SECRET")

# send
notificationapi.send({
  #The ID of the notification you wish to send. You can find this
  #value from the dashboard.
  type: 'order_tracking',
  # The user to send the notification to.
  to: {
    id: 'spongebob.squarepants',
    email: 'spongebob@squarepants.com', # required for email notifications
    number: '+15005550006'
  },
  email: {
    subject: 'Hello',
    html: '<h1>Hello, world!</h1>'
  },
  sms: { message: 'Hello, world!' },
  inapp: {
    title: 'Hello', url:
    'https://example.com',
    image: 'https://example.com/image.png'
  },
  mobile_push: {
    title: 'Hello',
    message: 'Hello, world!'
  },
  web_push: {
    title: 'Hello',
    message: 'Hello, world!',
    icon: 'https://example.com/icon.png',
    url: 'https://example.com'
  },
  call: { message: 'This is a test call from NotificationAPI.' },
  slack: { text: 'Hello, world!' }
});

TIP

Prefer using templates? Keep your content in the dashboard and pass only dynamic parameters. See Server reference · send for template-based examples.

FAQ

Where do I find my clientId and clientSecret?

You can find your credentials in the NotificationAPI dashboard under the Environments section.

What parameters can I pass to customize notifications?

Parameters allow you to personalize notification content with dynamic values. Any parameter you define in your notification template (using {{parameter_name}} syntax) can be passed in the parameters object. Common examples include names, order details, URLs, and dates.

How do I handle different regions?

NotificationAPI supports multiple regions:

US (default): https://api.notificationapi.com
Canada: https://api.ca.notificationapi.com
Europe: https://api.eu.notificationapi.com

Pass the appropriate URL when initializing the SDK or making API calls.

Can I schedule notifications for the future?

Yes! You can schedule notifications by adding a scheduledDate parameter to your send request. Learn more in our scheduling documentation.

Need more help?

If you need help, reach out through our live chat or Slack community.