Python Novu SDK

The Python Novu SDK and package provides a fluent and expressive interface for interacting with Novu's API and managing notifications.

Install

To install this package

# Via pip
pip install novu

# Via poetry
poetry add novu

Contents

• Install
• Quick start
• Code Snippet Examples
  • Events
  • Subscribers
  • Topics
  • Feeds
  • Environments
• Go further
• Development

Quick start

This package is a wrapper of all the resources offered by Novu, we will just start by triggering an event on Novu.

To do this, you will need to:

1. Create your first notification workflow and keep in mind the identifier to trigger the workflow: https://docs.novu.co/overview/quickstart/general-quickstart#create-a-workflow
2. Retrieve your API key from the Novu dashboard directly in the settings section: https://web.novu.co/settings
3. Write code to trigger your first event:

from novu.api import EventApi

event_api = EventApi("https://api.novu.co", "<NOVU_API_KEY>")
event_api.trigger(
    name="<YOUR_WORKFLOW_ID>",  # The workflow ID is the slug of the workflow name. It can be found on the workflow page.
    recipients="<YOUR_SUBSCRIBER_ID>",
    payload={},  # Your Novu payload goes here
)

This will trigger a notification to the subscribers.

Code Snippet Examples

Events

Firstly, make imports and declare the needed variables this way:

from novu.api import EventApi

url = "https://api.novu.co"
api_key = "<NOVU_API_KEY>"

# You can sign up on https://web.novu.co to get your API key from https://web.novu.co/settings

Trigger an event - Send notification to subscribers:

from novu.api import EventApi

novu = EventApi(url, api_key).trigger(
    name="digest-workflow-example",  # This is the Workflow ID. It can be found on the workflow page.
    recipients="<SUBSCRIBER_IDENTIFIER>", # The subscriber ID can be gotten from the dashboard.
    payload={},  # Your custom Novu payload goes here
)

Bulk Trigger events - Trigger multiple events at once:

from novu.dto.event import InputEventDto
from novu.api import EventApi

url = "https://api.novu.co"
api_key = "<NOVU_API_KEY>"

event_1 = InputEventDto(
    name="digest-workflow-example",  # The workflow ID is the slug of the workflow name. It can be found on the workflow page.
    recipients="<SUBSCRIBER_IDENTIFIER>",
    payload={},  # Your custom Novu payload goes here
)
event_2 = InputEventDto(
    name="digest-workflow-example",
    recipients="<SUBSCRIBER_IDENTIFIER>",
    payload={},
)

novu = EventApi("https://api.novu.co", api_key).trigger_bulk(events=[event1, event2])

Include actor field:

from novu.api import EventApi

novu = EventApi(url, api_key).trigger(
    name="workflow_trigger_identifier",
    recipients="subscriber_id",
    actor={
        "subscriberId": "subscriber_id_actor"
    },
    payload={
        "key":"value"
    },
)

Broadcast to all current subscribers:

novu = EventApi(url, api_key).broadcast(
    name="digest-workflow-example",
    payload={"customVariable": "value"},  # Optional
)

Subscribers

from novu.dto.subscriber import SubscriberDto
from novu.api.subscriber import SubscriberApi

url = "https://api.novu.co"
api_key = "<NOVU_API_KEY>"

# Define a subscriber instance
subscriber = SubscriberDto(
    email="novu_user@mail.com",
    subscriber_id="82a48af6ac82b3cc2157b57f", #This is what the subscriber_id looks like
    first_name="",  # Optional
    last_name="",  # Optional
    phone="",  # Optional
    avatar="",  # Optional
)

# Create a subscriber
novu = SubscriberApi(url, api_key).create(subscriber)

# Get a subscriber
novu = SubscriberApi(url, api_key).get(subscriber_id)

# Get list of subscribers
novu = SubscriberApi(url, api_key).list()

Topics

from novu.api import TopicApi

url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"

# Create a topic
novu = TopicApi(url, api_key).create(
    key="new-customers", name="New business customers"
)

# Get a topic
novu = TopicApi(url, api_key).get(key="new-customers")

# List topics
novu = TopicApi(url, api_key).list()

# Rename a topic
novu = TopicApi(url, api_key).rename(key="new-customers", name="New business customers")

# Subscribe a list of subscribers to a topic
novu = TopicApi(url, api_key).subscribe(key="old-customers", subscribers="<LIST_OF_SUBSCRIBER_IDs>")

# Unsubscribe a list of subscribers from a topic
novu = TopicApi(url, api_key).unsubscribe(key="old-customers", subscribers="<LIST_OF_SUBSCRIBER_IDs>")

Feeds

from novu.api.feed import FeedApi

url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"

# Create a Feed
novu = FeedApi(url, api_key).create(name="<SUPPLY_NAME_FOR_FEED>")

# Delete a Feed
FeedApi(url, api_key).delete(feed_id="<FEED_NOVU_INTERNAL_ID>")

# List feeds
novu = FeedApi(url, api_key).list()

Environments

from novu.api.environment import EnvironmentApi

url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"

# Create an Environment
novu = EnvironmentApi(url, api_key).create(
    name="<INSERT_NAME>",
    parent_id="<INSERT_PARENT_ID>" # Optional. Defaults to None
)

# # List existing environments
novu = EnvironmentApi(url, api_key).list()

# # Get the current environment
novu = EnvironmentApi(url, api_key).current()

# # Retrieve an environment's API_KEY
novu = EnvironmentApi(url, api_key).api_keys()

Tenants

from novu.api.tenant import TenantApi

url = "<NOVU_URL>"
api_key = "<NOVU_API_KEY>"

# Create an Environment
tenant = TenantApi(url, api_key).create(
    identifier="<INSERT_UNIQUE_TENANT_ID>",
    name="<INSERT_NAME>",
    data={} # Optional. Defaults to {}
)

# List existing tenants
tenants = TenantApi(url, api_key).list()
tenants = TenantApi(url, api_key).list(page=1, limit=10)

# Get a tenant
tenant = TenantApi(url, api_key).get("<TENANT-IDENTIFIER>")

# Patch some field of a tenant
tenant = TenantApi(url, api_key).patch(
    "<CURRENT-TENANT-IDENTIFIER>",
    identifier="<NEW-IDENTIFIER>",
    name="<NEW-NAME>",
    data="<NEW-DATA>"
)

# Delete a tenant
TenantApi(url, api_key).delete("<TENANT-IDENTIFIER>")

Go further

After a quick start with the SDK, you'll quickly get to grips with the advanced use of the SDK and the other APIs available.

For this purpose, documentation is available here: https://novu-python.readthedocs.io/

Development

# install deps
poetry install

# pre-commit
poetry run pre-commit install --install-hook
poetry run pre-commit install --install-hooks --hook-type commit-msg

Contributing

Feature requests, bug reports and pull requests are welcome. Please create an issue.

Support and Feedback

Be sure to visit the Novu official documentation website for additional information about our SDK. If you need additional assistance, join our Discord server here.

License

Novu Python SDK is licensed under the MIT License - see the LICENSE file for details.