README.md

Subscribers

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 - Search subscribers
• create - Create a subscriber
• get - Retrieve a subscriber
• update - Update a subscriber
• delete - Delete a subscriber
• createBulk - Bulk create subscribers
• updatePreferences - Update subscriber preferences
• updateCredentials - Update provider credentials
• removeCredentials - Delete provider credentials
• markAllMessages - Update all notifications state

search

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

Parameter	Type	Required	Description
request	SubscribersControllerSearchSubscribersRequest	✔️	The request object to use for the request.

Response

SubscribersControllerSearchSubscribersResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
failIfExists	Optional<Boolean>	➖	If true, the request will fail if a subscriber with the same subscriberId already exists
idempotencyKey	Optional<String>	➖	A header for idempotency purposes
body	CreateSubscriberRequestDto	✔️	N/A

Response

SubscribersControllerCreateSubscriberResponse

Errors

Error Type	Status Code	Content Type
models/errors/SubscriberResponseDtoException	409	application/json
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
subscriberId	String	✔️	The identifier of the subscriber
idempotencyKey	Optional<String>	➖	A header for idempotency purposes

Response

SubscribersControllerGetSubscriberResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
subscriberId	String	✔️	The identifier of the subscriber
idempotencyKey	Optional<String>	➖	A header for idempotency purposes
body	PatchSubscriberRequestDto	✔️	N/A

Response

SubscribersControllerPatchSubscriberResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
subscriberId	String	✔️	The identifier of the subscriber
idempotencyKey	Optional<String>	➖	A header for idempotency purposes

Response

SubscribersControllerRemoveSubscriberResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
idempotencyKey	Optional<String>	➖	A header for idempotency purposes
body	BulkSubscriberCreateDto	✔️	N/A

Response

SubscribersV1ControllerBulkCreateSubscribersResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
subscriberId	String	✔️	The identifier of the subscriber
idempotencyKey	Optional<String>	➖	A header for idempotency purposes
body	PatchSubscriberPreferencesDto	✔️	N/A

Response

SubscribersControllerUpdateSubscriberPreferencesResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
subscriberId	String	✔️	N/A
idempotencyKey	Optional<String>	➖	A header for idempotency purposes
body	UpdateSubscriberChannelRequestDto	✔️	N/A

Response

SubscribersV1ControllerUpdateSubscriberChannelResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 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

Parameter	Type	Required	Description
subscriberId	String	✔️	N/A
providerId	String	✔️	N/A
idempotencyKey	Optional<String>	➖	A header for idempotency purposes

Response

SubscribersV1ControllerDeleteSubscriberCredentialsResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 5XX	*/*

markAllMessages

Update all subscriber in-app (inbox) notifications state such as read, unread, seen or unseen by subscriberId.

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

Parameter	Type	Required	Description
subscriberId	String	✔️	N/A
idempotencyKey	Optional<String>	➖	A header for idempotency purposes
body	MarkAllMessageAsRequestDto	✔️	N/A

Response

SubscribersV1ControllerMarkAllUnreadAsReadResponse

Errors

Error Type	Status Code	Content Type
models/errors/ErrorDto	414	application/json
models/errors/ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models/errors/ValidationErrorDto	422	application/json
models/errors/ErrorDto	500	application/json
models/errors/APIException	4XX, 5XX	*/*