OpenParable
Skip to content
← Back to skills

Novu Manage Subscribers

Apps & Automation
novu-manage-subscribers

Novu Manage Subscribers is an Agent Skill for apps & automation published in the novuhq/novu repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/novuhq/novu/blob/HEAD/docs/.mintlify/skills/manage-subscribers/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/novu-manage-subscribers, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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: "[email protected]",      // 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: "[email protected]",
});

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: "[email protected]", firstName: "Alice" },
    { subscriberId: "user-2", email: "[email protected]", firstName: "Bob" },
    { subscriberId: "user-3", email: "[email protected]", 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

  1. subscriberId is YOUR user ID — it bridges your system to Novu. Use a stable, unique identifier from your database.
  2. 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.
  3. Subscriber data is per-environment — dev, staging, and production have separate subscriber records.
  4. Topics must exist before triggering — create the topic and add subscribers before sending to it.
  5. Deleting a subscriber doesn't delete their notifications — existing notifications remain in the system.
  6. 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