novu-manage-subscribers

Create, update, search, and delete subscribers in Novu. Manage topics for group-based notification targeting. Set subscriber credentials for push and chat channels. Use when managing notification recipients, creating subscriber records, organizing subscribers into topics, or configuring channel-specific credentials.

Quality

93%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Manage Subscribers

Subscribers are the recipients of your notifications. Each subscriber has a unique subscriberId — typically your application's user ID.

SDK Setup

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: process.env.NOVU_SECRET_KEY,
});

Create a Subscriber

await novu.subscribers.create({
  subscriberId: "user-123",       // required — your system's user ID
  email: "jane@example.com",      // optional
  firstName: "Jane",              // optional
  lastName: "Doe",                // optional
  phone: "+15551234567",          // optional
  avatar: "https://example.com/jane.jpg",  // optional
  locale: "en-US",                // optional
  timezone: "America/New_York",   // optional
  data: {                         // optional — custom key-value data
    plan: "pro",
    company: "Acme Inc",
  },
});

Only subscriberId is required. All other fields are optional.

Retrieve a Subscriber

const subscriber = await novu.subscribers.retrieve("user-123");

Search Subscribers

const results = await novu.subscribers.search({
  email: "jane@example.com",
});

Update a Subscriber

await novu.subscribers.patch(
  { firstName: "Jane", data: { plan: "enterprise" } },
  // subscriberId
  "user-123"
);

Delete a Subscriber

await novu.subscribers.delete("user-123");

Bulk Create

Create multiple subscribers at once. 500 subscribers can be created in one request.

await novu.subscribers.createBulk({
  subscribers: [
    { subscriberId: "user-1", email: "alice@example.com", firstName: "Alice" },
    { subscriberId: "user-2", email: "bob@example.com", firstName: "Bob" },
    { subscriberId: "user-3", email: "carol@example.com", firstName: "Carol" },
  ],
});

Topics

Topics are named groups of subscribers. Use them to send notifications to multiple subscribers at once.

Create a Topic

await novu.topics.create({
  key: "engineering-team",
  name: "Engineering Team",
});

Add Subscribers to a Topic

await novu.topics.subscriptions.create(
  { subscriptions: ["subscriberId-1", "subscriberId-2", "subscriberId-3"] },
  "engineering-team-topic"
);

Remove Subscribers from a Topic

await novu.topics.subscriptions.delete(
  { subscriptions: ["subscriberId-1", "subscriberId-2"] },
  "engineering-team-topic"
);

List Topics

const topics = await novu.topics.list({

});

Delete a Topic

await novu.topics.delete("engineering-team-topic");

Trigger to a Topic

See trigger-notification for topic trigger examples.

await novu.trigger({
  workflowId: "project-update",
  to: { type: "Topic", topicKey: "engineering-team-topic" },
  payload: { message: "Sprint review at 3pm" },
});

Subscriber Credentials

Set channel-specific credentials for push and chat integrations.

FCM Push Token

await novu.subscribers.credentials.update(
  { 
    providerId: "fcm", 
    //  use integrationIdentifier if there are multiple fcm type active integrations
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["fcm-device-token-here"] } 
  },
  "subsriberId-1"
);

APNS Push Token

await novu.subscribers.credentials.update(
  { 
    providerId: "apns", 
    // use integrationIdentifier if there are multiple apns type active integrations
    integrationIdentifier: "fcm-abc-123", 
    credentials: { deviceTokens: ["apns-device-token-here"] } 
  },
  "user-123"
);

Common Pitfalls

subscriberId is YOUR user ID — it bridges your system to Novu. Use a stable, unique identifier from your database.
Subscribers are auto-created on trigger — if you pass a full subscriber object in to when triggering, Novu creates the subscriber if it doesn't exist. But explicit creation gives you more control.
Subscriber data is per-environment — dev, staging, and production have separate subscriber records.
Topics must exist before triggering — create the topic and add subscribers before sending to it.
Deleting a subscriber doesn't delete their notifications — existing notifications remain in the system.
Adding non existent subscriber to topic - if non existent subscriber is added to topic, it is not autocreated in that environment and hence not added to the topic. Always create subscribers before adding into the topic

References

Repository: novuhq/novu
Path: docs/.mintlify/skills/manage-subscribers/SKILL.md
Commit: d921755

Last updated: about 12 hours ago
First committed: about 1 month ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.