API

This module is used to gather all python wrappers used to describe resources in Novu API.

In this SDK, we choose to split the Novu API by business resource to simplify its complexity.

class novu.api.BlueprintApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around blueprints in Novu

get_by_id(template_id: str) → BlueprintDto

Get a blueprint by ID

Parameters:: template_id – The ID of the blueprint
Returns:: The blueprint instance

get_grouped_by_category() → GroupedBlueprintDto

Get blueprints grouped by category

Returns:: Grouped blueprints instance

class novu.api.ChangeApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around changes in API

apply(change_id: str) → PaginatedChangeDto

Apply one change using its ID

Parameters:: change_ids – A change ID to apply.
Returns:: Paginated changes

bulk_apply(change_ids: List[str]) → Generator[ChangeDto, None, None]

Apply a list of changes using their IDs

Parameters:: change_ids – The list of IDs to apply
Yields:: Parsed Change from results list

count() → int

Get the number of changes

Returns:: Number of changes

list(page: int | None = None, limit: int | None = None, promoted: str = 'false') → PaginatedChangeDto

List existing changes

Parameters:

page – Page to retrieve. Defaults to None.
limit – Size of the page to retrieve. Defaults to None.
promoted – Required string to retrieve changes.

Returns:

Paginated list of change

class novu.api.EnvironmentApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around environments in Novu

api_keys() → Iterator[EnvironmentApiKeyDto]

Remove a environment using it’s identifier

Yields:: Mapped environment’s api keys

create(name: str, parent_id: str | None = None) → EnvironmentDto

Create a new environment using it’s name

Parameters:

name – The name of the environment to create
parent_id – The parent of the environment to create. Default to None.

Returns:

Mapped created environment

current() → EnvironmentDto

Retrieve the current environment

Returns:: Current environment mapped to DTO

list() → Iterator[EnvironmentDto]

List existing environments

Yields:: Mapped environment

regenerate_api_key() → Iterator[EnvironmentApiKeyDto]

Regenerate an environment api key

Yields:: Mapped environment’s api key

class novu.api.EventApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around events in Novu

broadcast(name: str, payload: dict, overrides: dict | None = None, transaction_id: str | None = None, actor: str | None = None, tenant: str | None = None)

Trigger a broadcast event to all existing subscribers, could be used to send announcements, etc.

Parameters:

name – The name of the template trigger to activate.
payload – A JSON serializable python dict to pass additional custom information that could be used to render the template, or perform routing rules based on it. This data will also be available when fetching the notifications feed from the API to display certain parts of the UI.
overrides – A JSON serializable python dict used to override provider specific configurations. Defaults to None.
transaction_id – A unique ID for this transaction, we will generated a UUID if not provided.
actor – It is used to display the Avatar of the provided actor’s subscriber id. Defaults to None.
tenant – It is used to specify a tenant context during trigger event. If a new tenant object is provided, we will create a new tenant.

Returns:

Create Event definition in Novu

delete(transaction_id: str) → None

Using a previously generated transaction ID during the event trigger, will cancel any active or pending workflows. This is useful to cancel active digests, delays, etc…

Parameters:: transaction_id – The transaction ID to cancel workflows

Trigger event is the main way to send notification to subscribers.

The trigger ID is used to match the particular template associated whit it.

Note

If you want to use topic, please use trigger_topic() instead

Warning

For the “recipients” attribute, the part allowing the dynamic creation of subscribers in the Novu AP was deliberately removed from the wrapper to force you to pre-create them. It is for us a good practice that we must begin to use for long-term programming with the platform (reuse of actor during the sending, subscription, management of preferences …).

Parameters:

name – The name of the template trigger to activate.
recipients – A subscriber ID (or a list of subscriber ID) to reach with this trigger
payload – A JSON serializable python dict to pass additional custom information that could be used to render the template, or perform routing rules based on it. This data will also be available when fetching the notifications feed from the API to display certain parts of the UI.
overrides – A JSON serializable python dict used to override provider specific configurations. Defaults to None.
transaction_id – A unique ID for this transaction, we will generated a UUID if not provided.
actor – It is used to display the Avatar of the provided actor’s subscriber id. Defaults to None.
tenant – It is used to specify a tenant context during trigger event. If a new tenant object is provided, we will create a new tenant.

Returns:

Create Event definition in Novu

trigger_bulk(events: List[InputEventDto]) → List[EventDto]

Trigger events in a bulk action to reduce the amount of api calls. Using this endpoint you can trigger multiple events at once, to avoid multiple calls to the API. The bulk API is limited to 100 events per request.

Parameters:: events (List[InputEventDto]) – List of input events that should be sent.
Returns:: List of created Novu events.
Return type:: List[EventDto]

Trigger event is the main way to send notification to topic’s subscribers.

The trigger ID is used to match the particular template associated whit it.

Note

If you want to use subscriber ID, please use trigger() instead

Parameters:

name – The name of the template trigger to activate.
topics – A TriggerTopicDto (or a list of topic) to reach with this trigger
payload – A JSON serializable python dict to pass additional custom information that could be used to render the template, or perform routing rules based on it. This data will also be available when fetching the notifications feed from the API to display certain parts of the UI.
overrides – A JSON serializable python dict used to override provider specific configurations. Defaults to None.
transaction_id – A unique ID for this transaction, we will generated a UUID if not provided.
actor – It is used to display the Avatar of the provided actor’s subscriber id. Defaults to None.
tenant – It is used to specify a tenant context during trigger event. If a new tenant object is provided, we will create a new tenant.

Returns:

Create Event definition in Novu

class novu.api.ExecutionDetailApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around execution details in Novu

list(notification_id: str, subscriber_id: str) → Iterator[ExecutionDetailDto]

List existing execution details using provided notification and subscriber IDs

Parameters:

notification_id – The notification ID in Novu
subscriber_id – The subscriber ID in Novu

Yields:

Mapped execution detail

class novu.api.FeedApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around feeds in Novu

create(name: str) → FeedDto

Create a new feed using it’s name

Parameters:: name – The name of the feed to create
Returns:: Mapped created feed

delete(feed_id: str) → None

Remove a feed using it’s identifier

Parameters:: feed_id – The feed identifier in Novu internal storage system (_id)

list() → Iterator[FeedDto]

List existing feeds

Yields:: Mapped feed

class novu.api.InboundParseApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around inbound-parse functionality in API

validate_mx_record_setup() → bool

Validate the mx record setup for the inbound parse functionality

Returns:: If the mx record setup is well setup or not.

class novu.api.IntegrationApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around integrations in API

create(integration: IntegrationDto, check: bool = True) → IntegrationDto

Create a provider integration configuration

Parameters:

integration – Integration instance that you want to create.
check – If you want the Novu server to check his connection using given integration configuration. Defaults to True.

Returns:

The instance of the created integration

delete(integration_id: str) → None

Delete an integration definition

Parameters:: integration_id – The integration ID

limit(channel: Channel) → IntegrationChannelUsageDto

Get limit of the given channel (and usage)

Parameters:: channel – The channel to retrieve limits
Returns:: Channel usage definition (including usage and limit)

list(only_active: bool = False) → Iterator[IntegrationDto]

List configured integrations

Parameters:: only_active – Allow to retrieve only active integrations. Defaults to False.
Yields:: Instance of integrations

set_primary(integration_id: str) → IntegrationDto

Set an integration as primary :param integration_id: The integration ID

Raises:

HTTPError – Raise a 400 error when provided integration identifier is not found in the application
HTTPError – Raise a 401 error when you are not authorized to do this action

Returns:

The instance of the updated integration

status(provider_id: SmsProviderIdEnum | PushProviderIdEnum | ChatProviderIdEnum | EmailProviderIdEnum | InAppProviderIdEnum) → bool

Get webhook support status for a given provider

Parameters:: provider_id – The provider ID
Returns:: If the provider support webhook

update(integration: IntegrationDto, check: bool = True) → IntegrationDto

Update an integration configuration

Parameters:

integration – The instance of the integration to update
check – If you want the Novu server to check his connection using given integration configuration. Defaults to True.

Returns:

The instance of the updated integration

class novu.api.LayoutApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around layout in API

create(layout: LayoutDto) → LayoutDto

Create a layout and return his identifier

Parameters:: layout – The instance of the layout to create
Returns:: The created layout identifier

delete(layout_id: str) → None

Remove a layout

Parameters:: layout_id – The ID of the layout to remove

get(layout_id: str) → LayoutDto

Get a layout using ID

Parameters:: layout_id – The layout ID
Returns:: The layout instance

list(page: int | None = None, limit: int | None = None) → PaginatedLayoutDto

List existing layouts

Parameters:

page – Page in pagination. Defaults to None.
limit – Size of the page in pagination. Defaults to None.

Returns:

Paginated list of layout

patch(layout: LayoutDto) → LayoutDto

Update a layout

Parameters:: layout – The instance of the layout to patch
Returns:: Updated layout instance

set_default(layout_id: str) → None

Set a layout as the default layout to use

Parameters:: layout_id – The layout ID

class novu.api.MessageApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around messages in Novu

delete(message_id: str) → bool

Deletes a message entity from the Novu platform

Parameters:: message_id – The message ID to delete
Returns:: This function answer if the delete is a success by parsing the acknowledged field in response.

list(limit: int = 10, page: int = 0, channel: str | None = None, subscriber_id: str | None = None, transaction_id: str | None = None) → PaginatedMessageDto

List messages

Parameters:

limit – The number of messages to fetch, defaults to 10
page – The page to fetch, defaults to 0
channel – The channel for the messages you wish to list. Defaults to None.
subscriber_id – The subscriberId for the subscriber you like to list messages for
transaction_id – The transactionId for the messages you wish to list. Defaults to None.

Returns:

Returned a paginated struct containing retrieved messages

stream(channel: str | None = None, subscriber_id: str | None = None) → PaginationIterator[MessageDto]

Stream all existing messages into an iterator.

Parameters:

channel – The channel for the messages you wish to list. Defaults to None.
subscriber_id – The subscriberId for the subscriber you like to list messages for

Returns:

An iterator on all messages available.

class novu.api.NotificationApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around notifications in API

get(notification_id: str) → ActivityNotificationDto: Trigger an event to get notification by id

graph_stats(id: str | None = None, start_date: str | None = None, end_date: str | None = None, days: int | None = None) → Iterator[ActivityGraphStatesDto]

Gets notifications graph stats.

Parameters:

id – is an optional parameter and should be a string. It represents the notification ID.
start_date – is an optional parameter and should be a string. It represents the start date for the stats.
end_date – is an optional parameter and should be a string. It represents the end date for the stats.
days – is an optional parameter and should be an integer. It represents the number of days to get stats for.

Returns:

An iterator on notifications graph stats in Novu

Trigger an event to get all notifications.

Parameters:

channels – A required parameter, should be an array of strings representing available notification channels, such as “in_app”, “email”, “sms”, “chat”, and “push”.
templates – A required parameter, should be an array of strings representing the notification templates.
emails – A required parameter, should be an array of strings representing the email addresses associated with the notification.
search – A required parameter, should be a string representing the search query.
page – An optional parameter with a default value of 0, representing the page number for search results.
transaction_id – A required parameter, should be a string representing the transaction ID associated with the notification.

Returns:

Gets notifications in Novu

stats() → Tuple[int, int]

Gets notifications stats

Returns:: Tuple including weekly and monthly sent notifications.

Stream all existing notifications into an iterator.

Parameters:

channels – A required parameter, should be an array of strings representing available notification channels, such as “in_app”, “email”, “sms”, “chat”, and “push”.
templates – A required parameter, should be an array of strings representing the notification templates.
emails – A required parameter, should be an array of strings representing the email addresses associated with the notification.
search – A required parameter, should be a string representing the search query.
transaction_id – A required parameter, should be a string representing the transaction ID associated with the notification.

Returns:

An iterator on all notifications available.

class novu.api.NotificationGroupApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around notification groups in API

create(name: str) → NotificationGroupDto

Method to create a new notification group

Parameters:: name – The name of the notification group.
Returns:: The created notification group.

delete(_id: str) → NotificationGroupDto

Method to delete a notification group

Parameters:: _id – The id of the notification group.
Returns:: The deleted notification group.

get(_id: str) → NotificationGroupDto

Method to get a notification group

Parameters:: _id – The id of the notification group.
Returns:: The notification group.

list() → PaginatedNotificationGroupDto

Method to list notification groups

Returns:: Paginated notification groups

patch(_id: str, name: str) → NotificationGroupDto

Method to patch a notification group

Parameters:

_id – The id of the notification group.
name – The name of the notification group.

Returns:

The patched notification group.

class novu.api.NotificationTemplateApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around notification templates in API

create(notification_template: NotificationTemplateFormDto) → NotificationTemplateDto

Create a template using the notification template form definition

Parameters:: notification_template – The notification template form definition
Returns:: Mapped notification template after it’s creation

delete(notification_template_id: str) → None

Delete a notification template using it’s ID

Parameters:: notification_template_id – The notification template ID

get(notification_template_id: str) → NotificationTemplateDto

Retrieve a notification template using it’s Novu ID

Parameters:: notification_template_id – The Novu ID of the notification template
Returns:: Mapped notification template

list(page: int | None = None, limit: int | None = None) → PaginatedNotificationTemplateDto

Method to list notification templates

Returns:: Paginated notification templates

stream() → PaginationIterator[NotificationTemplateDto]

Stream all existing workflows into an iterator.

Returns:: An iterator on all workflows available.

update(notification_template_id: str, notification_template: NotificationTemplateFormDto) → NotificationTemplateDto

Full update of a notification template, using it’s template form definition

Parameters:

notification_template_id – The Novu ID of the notification template
notification_template – The notification template from instance

Returns:

Mapped notification template after it’s update

update_status(notification_template_id: str, status: bool) → NotificationTemplateDto

Update a notification template status (active or not) using it’s ID and the requested status

Parameters:

notification_template_id – The Novu ID of the notification template
status – The activation status of the notification template

Returns:

Mapped notification template after it’s update

class novu.api.SubscriberApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around subscribers in API

bulk_create(subscribers: Iterator[SubscriberDto]) → BulkResultSubscriberDto

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.

Parameters:: subscribers – An iterator of subscribers instance to push to Novu
Returns:: Result of the bulk operation in Novu.

change_channel_preference(subscriber_id: str, template_id: str, channel: Channel, channel_enabled: bool) → SubscriberPreferenceDto

Change the subscriber preference for a targeted channel of given template

Parameters:

subscriber_id – The subscriber on which we want to change preference
template_id – The template on which we want to change preference
channel – The channel on which we want to change preference
channel_enabled – The new state of activation of the channel

Returns:

Updated subscriber preference of the targeted template

change_preference_state(subscriber_id: str, template_id: str, state: bool) → SubscriberPreferenceDto

Change the subscriber preference state (enabled or disabled) for a given template

Parameters:

subscriber_id – The subscriber identifier
template_id – The template identifier
state – The state of the subscriber preference for given template

Returns:

Updated subscriber preference of the targeted template

create(subscriber: SubscriberDto) → SubscriberDto

Method to push a given subscriber instance to Novu

Parameters:: subscriber – The subscriber instance to push to Novu
Returns:: The instance retrieved from Novu (populated after creation)

credentials(subscriber_id: str, provider_id: str, webhook_url: str | None = None, device_tokens: List[str] | None = None) → SubscriberDto

Update subscriber credentials associated to the delivery methods such as slack and push tokens

Parameters:

subscriber_id – The subscriber identifier
provider_id – The provider name (e.g: slack)
webhook_url – The webhook URL to set in the provider credentials. Defaults to None.
device_tokens – A list of device tokens to set in the provider credentials. Defaults to None.

Returns:

Updated subscriber

delete(subscriber_id: str) → None

Method used to delete a subscriber using his identifier

Parameters:: subscriber_id – The subscriber identifier

delete_credentials(subscriber_id: str, provider_id: SmsProviderIdEnum | PushProviderIdEnum | ChatProviderIdEnum | EmailProviderIdEnum | InAppProviderIdEnum) → None

Delete subscriber credentials such as slack and expo tokens.

Parameters:

subscriber_id – The subscriber identifier
provider_id – The provider identifier (e.g: slack)

get(subscriber_id: str) → SubscriberDto

Method to get a subscriber using his identifier

Parameters:: subscriber_id – The subscriber identifier
Returns:: The subscriber instance

list(page: int | None = None) → PaginatedSubscriberDto

Method to list subscriber

Parameters:: page – The page number. Defaults to 0.
Returns:: Paginated subscriber

online_status(subscriber_id: str, status: bool) → SubscriberDto

Used to update the subscriber is_online flag

Parameters:

subscriber_id – The subscriber identifier.
status – The subscriber is_online flag value.

Returns:

Updated subscriber

preferences(subscriber_id: str) → Iterator[SubscriberPreferenceDto]

Get the subscriber preferences

Parameters:: subscriber_id – The subscriber identifier
Yields:: Iterator of subscriber preference

put(subscriber: SubscriberDto) → SubscriberDto

Method to update a subscriber using his instance

Parameters:: subscriber – The subscriber instance to push
Returns:: Updated subscriber instance from Novu API

stream() → PaginationIterator[SubscriberDto]

Stream all existing subscribers into an iterator.

Returns:: An iterator on all subscribers available.

unseen_notifications(subscriber_id: str) → int

Retrieve the number of unseen notification for subscribers feed

Parameters:: subscriber_id – The subscriber identifier
Returns:: The number of unseen notification

class novu.api.TenantApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around tenants in API

create(identifier: str, name: str, data: dict | None = None) → TenantDto

Create a tenant

Parameters:

identifier – Identifier of the new tenant
name – Name of the new tenant
data – Data of the new tenant. Default to None.

Returns:

Created tenant

delete(identifier: str) → None

Remove a Tenant using his identifier

Parameters:: identifier – Current identifier of the tenant in Novu

get(identifier: str) → TenantDto

Retrieve a Tenant using his identifier

Note

This method is the easiest way to get the list of subscribers.

Parameters:: identifier – The tenant identifier (ID in Novu)
Returns:: TenantDto

list(page: int | None = None, limit: int | None = None) → PaginatedTenantDto

List existing tenants

Parameters:

page – Page to retrieve. Defaults to None.
limit – Size of the page to retrieve. Defaults to None.

Returns:

Paginated list of tenant

patch(reference: str, identifier: str | None = None, name: str | None = None, data: dict | None = None) → TenantDto

Edit a Tenant using his identifier

Parameters:

reference – Current identifier of the tenant in Novu
identifier – New identifier to set on the tenant
name – New name to set on the tenant
data – New data dict to set on the tenant

Returns:

TenantDto

stream() → PaginationIterator[TenantDto]

Stream all existing tenants into an iterator.

Returns:: An iterator on all tenants available.

class novu.api.TopicApi(url: str | None = None, api_key: str | None = None, requests_timeout: int | None = None, session: Session | None = None)

This class aims to handle all API methods around topics in API

create(key: str, name: str) → TopicDto

Create a topic

Parameters:

key – The topic key to create
name – The topic name to create

Returns:

Created topic (without name ?)

delete(key: str) → None

Delete a topic by its topic key if it has no subscribers

Parameters:: Key – The topic key to delete

get(key: str) → TopicDto

Retrieve a Topic using his key

Note

This method is the easiest way to get the list of subscribers.

Parameters:: key – The topic key (ID in Novu)
Returns:: Topic

list(page: int | None = None, limit: int | None = None, key: str | None = None) → PaginatedTopicDto

List existing topics

Parameters:

page – Page to retrieve. Defaults to None.
limit – Size of the page to retrieve. Defaults to None.
key – Filter list by a topic key. Defaults to None.

Returns:

Paginated list of topic

rename(key: str, name: str) → TopicDto

Rename a topic

Parameters:

key – The key of the topic to rename
name – The new name of the topic

Returns:

Renamed topic definition

subscribe(key: str, subscribers: List[str] | str) → Tuple[List[str], Dict[str, List[str]]]

Subscribe a list of subscribers to a topic

Parameters:

key – The key of the topic to subscribe
subscribers – The list of subscribers to subscribe

Returns:

First element returned is a list of succeeded subscriptions.

Second element returned is a dict of failed subscriptions (key the reason and value contains a list of reference which fail for the reason).

unsubscribe(key: str, subscribers: List[str] | str) → None

Unsubscribe a list of subscribers form a topic

Parameters:

key – The key of the topic to unsubscribe
subscribers – The list of subscribers to unsubscribe