Subscribers

In Novu, we call the entities designed to receive notifications as Subscribers. Each subscriber is unique and identified by a unique subscriberId.

Each subscriber has the following data points:

• User Data - Data stored in the subscriber object that you can easily access in your notification templates. This contains basic info such as first name, last name, avatar, locale, email, and phone. This data is fixed and structured.
• Custom Data - Apart from the above fixed structured user data, any unstructured custom data such as user's address, nationality, height, etc can also be stored in the data field using key-value pairs.
• Channel Specific Credentials - deviceTokens required to send push notifications and webhookUrl for chat channel providers can also be stored.

Subscriber attributes

Creating a subscriber

We support creating new subscriber using two ways, Just-in-time means sending complete subscriber data in to field while triggering or Ahead of Trigger means adding subscribers before triggering notification.

Just-in-time

A non-existing subscriber can be added by sending subscriber data in to field of the trigger method. If any subscriber with provided subscriberId does not exists, a new subscriber will be created. In this case, subscriber will be created first and then the trigger will be executed synchronously.

import { Novu } from '@novu/api';
 
const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});
 
await novu.trigger({
  workflowId: '<WORKFLOW_TRIGGER_IDENTIFIER>',
  to: {
    subscriberId: "subscriber_unique_identifier",
    firstName: "Albert",
    lastName: "Einstein",
    email: "albert@einstein.com",
    phone: "+1234567890",
  },
  payload: {
    customVariable: 'variableValue',
    organization: {
      logo: 'https://organization.com/logo.png',
    },
  },
});

When triggering the workflow, you must specify all required to fields per the channels in the workflow. For example, if an email step is included in the workflow, then the to.email field must be specified. Similarly if an SMS step is included, the to.phone field must be specified.

Hydrating users data from database

If you are defining workflows with code using @novu/framework, you can use the subscriberId to hydrate subscriber data directly from your database or other sources during workflow execution. This is useful when you don't want to store all the subscriber data in Novu.

Learn more about @novu/framework and how to use it to define workflows with code.

For example, you may have a welcome onboarding email that you trigger immediately after a user signs up, with the email only sent 1 hour after signup:

import { workflow } from '@novu/framework';
import { userDb } from '../db/userDb';
 
export const welcomeEmail = workflow('welcome-email', async ({ step, subscriber }) => {
  await step.delay('delay', () => ({ amount: 1, unit: 'hours' }));
 
  await step.email('send-email', async (controls) => {
    // Fetch user data from your database in real-time to
    // ensure up-to-date information
    const user = await userDb.findById(subscriber.subscriberId);
 
    return {
      subject: `Welcome, ${user.firstName}`,
      body: 'Welcome to our platform!',
    };
  });
});

Then, when you trigger the workflow, you can pass the subscriberId and the workflow will fetch the user data from your database in real-time:

await welcomeEmail.trigger({
  to: {
    subscriberId: '123',
    email: 'john.doe@domain.com',
  },
});

Ahead of Trigger

Create the subscriber and then trigger the notification to this subscriber. Here subscriberId is the required field and other fields are optional.

import { Novu } from '@novu/api';
 
const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});
 
await novu.subscribers.create({
  subscriberId: "subscriber_unique_identifier",
  firstName: "Albert",
  lastName: "Einstein",
  email: "albert@einstein.com",
  phone: "+1234567890",
  avatar: 'https://example.com/images/avatar.jpg',
  locale: 'en-US',
  data: { customKey1: 'customVal1', customKey2: 'customVal2' },
});

Novu will create a subscriber if one does not exist and will update the existing subscriber. You can call this function during registration or signup to make sure the subscriber data is up-to-date, if you wish to save additional attributes with a subscriber, you can pass additional custom data in the data field as key-value pairs.

Bulk subscriber creation

You can create subscribers in bulk (up to 500 at once) via the SDKs or API.

import { Novu } from "@novu/api";
 
const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});
 
await novu.subscribers.createBulk({
  subscribers: [
    {
      subscriberId: "albert_einstein_user_id",
      firstName: "Albert",
      lastName: "Einstein",
      email: "albert@einstein.com",
      phone: "+1234567890",
      avatar: 'https://example.com/images/albert_einstein.jpg',
      locale: 'en-US',
      data: { isScientist: true },
    },
    {
      subscriberId: "nikola_tesla_user_id",
      firstName: "Nikola",
      lastName: "Tesla",
      email: "nikola@tesla.com",
      phone: "+1234567890",
      avatar: 'https://example.com/images/nikola_tesla.jpg',
      locale: 'en-US',
      data: { isInventor: true },
    }
  ],
});

Manage subscribers from dashboard

Subscribers can be managed from the dashboard by navigating to the Subscribers page.