Subscribers

(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

list - Get subscribers
create - Create subscriber
retrieve_legacy - Get subscriber
update - Update subscriber
~~delete_legacy~~ - Delete subscriber ⚠️ Deprecated
create_bulk - Bulk create subscribers
search - Search for subscribers
retrieve - Get subscriber
patch - Patch subscriber
delete - Delete subscriber

list

Returns a list of subscribers, could paginated using the page and limit query parameter

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.list()

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description
`page`	Optional[float]	➖	N/A
`limit`	Optional[float]	➖	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersV1ControllerListSubscribersResponse

Errors

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

create

Creates a subscriber entity, in the Novu platform. The subscriber will be later used to receive notifications, and access notification feeds. Communication credentials such as email, phone number, and 3 rd party credentials i.e slack tokens could be later associated to this entity.

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.create(create_subscriber_request_dto={
        "subscriber_id": "<id>",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`create_subscriber_request_dto`	models.CreateSubscriberRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersV1ControllerCreateSubscriberResponse

Errors

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

retrieve_legacy

Get subscriber by your internal id used to identify the subscriber

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.retrieve_legacy(subscriber_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscriber_id`	str	✔️	N/A
`include_topics`	Optional[bool]	➖	Includes the topics associated with the subscriber
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersV1ControllerGetSubscriberResponse

Errors

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

update

Used to update the subscriber entity with new information

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.update(subscriber_id="<id>", update_subscriber_request_dto={
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+1234567890",
        "avatar": "https://example.com/avatar.jpg",
        "locale": "en-US",
        "data": {
            "preferences": {
                "notifications": True,
                "theme": "dark",
            },
            "tags": [
                "premium",
                "newsletter",
            ],
        },
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscriber_id`	str	✔️	N/A
`update_subscriber_request_dto`	models.UpdateSubscriberRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersV1ControllerUpdateSubscriberResponse

Errors

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

delete_legacy

Deletes a subscriber entity from the Novu platform

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

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.delete_legacy(subscriber_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscriber_id`	str	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersV1ControllerRemoveSubscriberResponse

Errors

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

create_bulk

  Using this endpoint you can create multiple subscribers at once, to avoid multiple calls to the API.
  The bulk API is limited to 500 subscribers per request.

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.create_bulk(bulk_subscriber_create_dto={
        "subscribers": [
            {
                "subscriber_id": "<id>",
            },
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`bulk_subscriber_create_dto`	models.BulkSubscriberCreateDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersV1ControllerBulkCreateSubscribersResponse

Errors

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

search

Search for subscribers

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.search()

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`request`	models.SubscribersControllerSearchSubscribersRequest	✔️	The request object to use for the request.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersControllerSearchSubscribersResponse

Errors

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

retrieve

Get subscriber by your internal id used to identify the subscriber

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.retrieve(subscriber_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscriber_id`	str	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersControllerGetSubscriberResponse

Errors

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

patch

Patch subscriber by your internal id used to identify the subscriber

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.patch(subscriber_id="<id>", patch_subscriber_request_dto={})

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscriber_id`	str	✔️	N/A
`patch_subscriber_request_dto`	models.PatchSubscriberRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersControllerPatchSubscriberResponse

Errors

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

delete

Deletes a subscriber entity from the Novu platform

Example Usage

from novu_py import Novu
import os

with Novu(
    secret_key=os.getenv("NOVU_SECRET_KEY", ""),
) as novu:

    res = novu.subscribers.delete(subscriber_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`subscriber_id`	str	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SubscribersControllerRemoveSubscriberResponse

Errors

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

Files

README.md

Latest commit

History

README.md

File metadata and controls

Subscribers

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

retrieve_legacy

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

delete_legacy

Example Usage

Parameters

Response

Errors

create_bulk

Example Usage

Parameters

Response

Errors

search

Example Usage

Parameters

Response

Errors

retrieve

Example Usage

Parameters

Response

Errors

patch

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors