Subscribers

July 8, 2026 ยท View on GitHub

Overview

A subscriber in Novu represents someone who should receive a message. A subscriber's profile information contains important attributes about the subscriber that will be used in messages (name, email). The subscriber object can contain other key-value pairs that can be used to further personalize your messages. https://docs.novu.co/subscribers/subscribers

Available Operations

Search subscribers by their email, phone, subscriberId and name. The search is case sensitive and supports pagination.Checkout all available filters in the query section.

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersControllerSearchSubscribersRequest;
import co.novu.models.operations.SubscribersControllerSearchSubscribersResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersControllerSearchSubscribersRequest req = SubscribersControllerSearchSubscribersRequest.builder()
                .limit(10d)
                .build();

        SubscribersControllerSearchSubscribersResponse res = sdk.subscribers().search()
                .request(req)
                .call();

        if (res.listSubscribersResponseDto().isPresent()) {
            System.out.println(res.listSubscribersResponseDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
requestSubscribersControllerSearchSubscribersRequest:heavy_check_mark:The request object to use for the request.

Response

SubscribersControllerSearchSubscribersResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

create

Create a subscriber with the subscriber attributes. subscriberId is a required field, rest other fields are optional, if the subscriber already exists, it will be updated

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.components.CreateSubscriberRequestDto;
import co.novu.models.errors.*;
import co.novu.models.operations.SubscribersControllerCreateSubscriberResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws SubscriberResponseDtoException, ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersControllerCreateSubscriberResponse res = sdk.subscribers().create()
                .body(CreateSubscriberRequestDto.builder()
                    .subscriberId("<id>")
                    .firstName("John")
                    .lastName("Doe")
                    .email("john.doe@example.com")
                    .phone("+1234567890")
                    .avatar("https://example.com/avatar.jpg")
                    .locale("en-US")
                    .timezone("America/New_York")
                    .build())
                .call();

        if (res.subscriberResponseDto().isPresent()) {
            System.out.println(res.subscriberResponseDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
failIfExistsOptional<Boolean>:heavy_minus_sign:If true, the request will fail if a subscriber with the same subscriberId already exists
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes
bodyCreateSubscriberRequestDto:heavy_check_mark:N/A

Response

SubscribersControllerCreateSubscriberResponse

Errors

Error TypeStatus CodeContent Type
models/errors/SubscriberResponseDtoException409application/json
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

get

Retrieve a subscriber by its unique key identifier subscriberId. subscriberId field is required.

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersControllerGetSubscriberResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersControllerGetSubscriberResponse res = sdk.subscribers().get()
                .subscriberId("<id>")
                .call();

        if (res.subscriberResponseDto().isPresent()) {
            System.out.println(res.subscriberResponseDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
subscriberIdString:heavy_check_mark:The identifier of the subscriber
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes

Response

SubscribersControllerGetSubscriberResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

update

Update a subscriber by its unique key identifier subscriberId. subscriberId is a required field, rest other fields are optional

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.components.PatchSubscriberRequestDto;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersControllerPatchSubscriberResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersControllerPatchSubscriberResponse res = sdk.subscribers().update()
                .subscriberId("<id>")
                .body(PatchSubscriberRequestDto.builder()
                    .firstName("John")
                    .lastName("Doe")
                    .email("john.doe@example.com")
                    .phone("+1234567890")
                    .avatar("https://example.com/avatar.jpg")
                    .locale("en-US")
                    .timezone("America/New_York")
                    .build())
                .call();

        if (res.subscriberResponseDto().isPresent()) {
            System.out.println(res.subscriberResponseDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
subscriberIdString:heavy_check_mark:The identifier of the subscriber
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes
bodyPatchSubscriberRequestDto:heavy_check_mark:N/A

Response

SubscribersControllerPatchSubscriberResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

delete

Deletes a subscriber entity from the Novu platform along with associated messages, preferences, and topic subscriptions. subscriberId is a required field.

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersControllerRemoveSubscriberResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersControllerRemoveSubscriberResponse res = sdk.subscribers().delete()
                .subscriberId("<id>")
                .call();

        if (res.removeSubscriberResponseDto().isPresent()) {
            System.out.println(res.removeSubscriberResponseDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
subscriberIdString:heavy_check_mark:The identifier of the subscriber
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes

Response

SubscribersControllerRemoveSubscriberResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

createBulk

  Using this endpoint multiple subscribers can be created at once. The bulk API is limited to 500 subscribers per request.

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.components.BulkSubscriberCreateDto;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersV1ControllerBulkCreateSubscribersResponse;
import java.lang.Exception;
import java.util.List;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersV1ControllerBulkCreateSubscribersResponse res = sdk.subscribers().createBulk()
                .body(BulkSubscriberCreateDto.builder()
                    .subscribers(List.of())
                    .build())
                .call();

        if (res.bulkCreateSubscriberResponseDto().isPresent()) {
            System.out.println(res.bulkCreateSubscriberResponseDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes
bodyBulkSubscriberCreateDto:heavy_check_mark:N/A

Response

SubscribersV1ControllerBulkCreateSubscribersResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

updatePreferences

Update subscriber preferences by its unique key identifier subscriberId. workflowId is optional field, if provided, this API will update that workflow preference, otherwise it will update global preferences

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.components.*;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersControllerUpdateSubscriberPreferencesResponse;
import java.lang.Exception;
import java.util.List;
import java.util.Map;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersControllerUpdateSubscriberPreferencesResponse res = sdk.subscribers().updatePreferences()
                .subscriberId("<id>")
                .body(PatchSubscriberPreferencesDto.builder()
                    .schedule(ScheduleDto.builder()
                        .isEnabled(true)
                        .weeklySchedule(WeeklySchedule.builder()
                            .monday(Monday.builder()
                                .isEnabled(true)
                                .hours(List.of(
                                    TimeRangeDto.builder()
                                        .start("09:00 AM")
                                        .end("05:00 PM")
                                        .build()))
                                .build())
                            .tuesday(Tuesday.builder()
                                .isEnabled(true)
                                .hours(List.of(
                                    TimeRangeDto.builder()
                                        .start("09:00 AM")
                                        .end("05:00 PM")
                                        .build()))
                                .build())
                            .wednesday(Wednesday.builder()
                                .isEnabled(true)
                                .hours(List.of(
                                    TimeRangeDto.builder()
                                        .start("09:00 AM")
                                        .end("05:00 PM")
                                        .build()))
                                .build())
                            .thursday(Thursday.builder()
                                .isEnabled(true)
                                .hours(List.of(
                                    TimeRangeDto.builder()
                                        .start("09:00 AM")
                                        .end("05:00 PM")
                                        .build()))
                                .build())
                            .friday(Friday.builder()
                                .isEnabled(true)
                                .hours(List.of(
                                    TimeRangeDto.builder()
                                        .start("09:00 AM")
                                        .end("05:00 PM")
                                        .build()))
                                .build())
                            .saturday(Saturday.builder()
                                .isEnabled(true)
                                .hours(List.of(
                                    TimeRangeDto.builder()
                                        .start("09:00 AM")
                                        .end("05:00 PM")
                                        .build()))
                                .build())
                            .sunday(Sunday.builder()
                                .isEnabled(true)
                                .hours(List.of(
                                    TimeRangeDto.builder()
                                        .start("09:00 AM")
                                        .end("05:00 PM")
                                        .build()))
                                .build())
                            .build())
                        .build())
                    .context(Map.ofEntries(
                        Map.entry("key", PatchSubscriberPreferencesDtoContextUnion.of("org-acme"))))
                    .build())
                .call();

        if (res.getSubscriberPreferencesDto().isPresent()) {
            System.out.println(res.getSubscriberPreferencesDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
subscriberIdString:heavy_check_mark:The identifier of the subscriber
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes
bodyPatchSubscriberPreferencesDto:heavy_check_mark:N/A

Response

SubscribersControllerUpdateSubscriberPreferencesResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

updateCredentials

Update credentials for a provider such as slack and FCM. providerId is required field. This API creates the deviceTokens or replaces the existing ones.

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.components.*;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersV1ControllerUpdateSubscriberChannelResponse;
import java.lang.Exception;
import java.util.List;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersV1ControllerUpdateSubscriberChannelResponse res = sdk.subscribers().updateCredentials()
                .subscriberId("<id>")
                .body(UpdateSubscriberChannelRequestDto.builder()
                    .providerId(ChatOrPushProviderEnum.SLACK)
                    .credentials(ChannelCredentials.builder()
                        .webhookUrl("https://example.com/webhook")
                        .channel("general")
                        .deviceTokens(List.of(
                            "token1",
                            "token2",
                            "token3"))
                        .alertUid("12345-abcde")
                        .title("Critical Alert")
                        .imageUrl("https://example.com/image.png")
                        .state("resolved")
                        .externalUrl("https://example.com/details")
                        .build())
                    .build())
                .call();

        if (res.subscriberResponseDto().isPresent()) {
            System.out.println(res.subscriberResponseDto().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
subscriberIdString:heavy_check_mark:N/A
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes
bodyUpdateSubscriberChannelRequestDto:heavy_check_mark:N/A

Response

SubscribersV1ControllerUpdateSubscriberChannelResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

removeCredentials

Delete subscriber credentials for a provider such as slack and FCM by providerId. This action is irreversible and will remove the credentials for the provider for particular subscriberId.

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersV1ControllerDeleteSubscriberCredentialsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersV1ControllerDeleteSubscriberCredentialsResponse res = sdk.subscribers().removeCredentials()
                .subscriberId("<id>")
                .providerId("<id>")
                .call();

        // handle response
    }
}

Parameters

ParameterTypeRequiredDescription
subscriberIdString:heavy_check_mark:N/A
providerIdString:heavy_check_mark:N/A
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes

Response

SubscribersV1ControllerDeleteSubscriberCredentialsResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*

markAllMessages

This API is deprecated, use v2 API instead. Update all subscriber in-app notifications state such as read, unread, seen or unseen by subscriberId.

:warning: DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.

Example Usage

package hello.world;

import co.novu.Novu;
import co.novu.models.components.MarkAllMessageAsRequestDto;
import co.novu.models.components.MarkAllMessageAsRequestDtoMarkAs;
import co.novu.models.errors.ErrorDto;
import co.novu.models.errors.ValidationErrorDto;
import co.novu.models.operations.SubscribersV1ControllerMarkAllUnreadAsReadResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorDto, ValidationErrorDto, Exception {

        Novu sdk = Novu.builder()
                .secretKey("YOUR_SECRET_KEY_HERE")
            .build();

        SubscribersV1ControllerMarkAllUnreadAsReadResponse res = sdk.subscribers().markAllMessages()
                .subscriberId("<id>")
                .body(MarkAllMessageAsRequestDto.builder()
                    .markAs(MarkAllMessageAsRequestDtoMarkAs.READ)
                    .build())
                .call();

        if (res.number().isPresent()) {
            System.out.println(res.number().get());
        }
    }
}

Parameters

ParameterTypeRequiredDescription
subscriberIdString:heavy_check_mark:N/A
idempotencyKeyOptional<String>:heavy_minus_sign:A header for idempotency purposes
bodyMarkAllMessageAsRequestDto:heavy_check_mark:N/A

Response

SubscribersV1ControllerMarkAllUnreadAsReadResponse

Errors

Error TypeStatus CodeContent Type
models/errors/ErrorDto414application/json
models/errors/ErrorDto400, 401, 403, 404, 405, 409, 413, 415application/json
models/errors/ValidationErrorDto422application/json
models/errors/ErrorDto500application/json
models/errors/APIException4XX, 5XX*/*