Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trysiren.io/llms.txt

Use this file to discover all available pages before exploring further.

This is the official Python SDK for the Siren notification platform.

​
Installation

pip install trysiren

​
Basic Usage

​
Synchronous Client

from siren import SirenClient

# Uses SIREN_API_KEY and SIREN_ENV environment variables
client = SirenClient()

# Send a direct message without template
message_id = client.message.send(
    recipient_value="alice@company.com",
    channel="EMAIL",
    body="Your account has been successfully verified. You can now access all features."
)

# Send a message using a template
message_id = client.message.send(
    recipient_value="U01UBCD06BB",
    channel="SLACK",
    template_name="welcome_template",
    template_variables={"user_name": "John"},
)

# Send a message with specific provider
from siren.models.messaging import ProviderCode
message_id = client.message.send(
    recipient_value="alice@company.com",
    channel="EMAIL",
    body="Your account has been successfully verified.",
    provider_name="email-provider",
    provider_code=ProviderCode.EMAIL_SENDGRID,
)

# Send a message using awesome template
message_id = client.message.send_awesome_template(
    recipient_value="U01UBCD06BB",
    channel="SLACK",
    template_identifier="awesome-templates/customer-support/escalation_required/official/casual.yaml",
    template_variables={
        "ticket_id": "123456",
        "customer_name": "John",
        "issue_summary": "Payment processing issue",
        "ticket_url": "https://support.company.com/ticket/123456",
        "sender_name": "Support Team"
    },
    provider_name="slack-provider",
    provider_code=ProviderCode.SLACK,
)

# Alternative initialization
client = SirenClient(api_key="YOUR_SIREN_API_KEY")  # default env is "prod"
# Or:
client = SirenClient(api_key="YOUR_SIREN_API_KEY", env="dev")

​
Asynchronous Client

from siren import AsyncSirenClient

# Using async context manager (recommended)
async with AsyncSirenClient() as client:
    message_id = await client.message.send(
        recipient_value="alice@company.com",
        channel="EMAIL",
        body="Your account has been successfully verified. You can now access all features."
    )

# Or manually managing the client
client = AsyncSirenClient()
try:
    message_id = await client.message.send(
        recipient_value="alice@company.com",
        channel="EMAIL",
        body="Your account has been successfully verified. You can now access all features."
    )
finally:
    await client.aclose()
All synchronous methods have a 1-to-1 asynchronous equivalent—just await them on the async client.

​
SDK Methods

The Siren Python SDK provides a clean, namespaced interface to interact with the Siren API. Below are the available methods organized by functionality.

​
Templates

MethodDescription
client.template.get()Retrieves a list of notification templates with optional filtering, sorting, and pagination
client.template.create()Creates a new notification template
client.template.update()Updates an existing notification template
client.template.delete()Deletes an existing notification template
client.template.publish()Publishes a template, making its latest draft version live

​
Channel Templates

MethodDescription
client.channel_template.create()Creates or updates channel-specific templates (EMAIL, SMS, etc.)
client.channel_template.get()Retrieves channel templates for a specific template version

​
Messaging

MethodDescription
client.message.send()Sends a message (with or without a template) to a recipient via a chosen channel
client.message.send_awesome_template()Sends a message using a template path/identifier
client.message.get_replies()Retrieves replies for a specific message ID
client.message.get_status()Retrieves the status of a specific message (SENT, DELIVERED, FAILED, etc.)

​
Workflows

MethodDescription
client.workflow.trigger()Triggers a workflow with given data and notification payloads
client.workflow.trigger_bulk()Triggers a workflow in bulk for multiple recipients
client.workflow.schedule()Schedules a workflow to run at a future time (once or recurring)

​
Webhooks

MethodDescription
client.webhook.configure_notifications()Configures webhook URL for receiving status updates
client.webhook.configure_inbound()Configures webhook URL for receiving inbound messages

​
Users

MethodDescription
client.user.add()Creates a new user or updates existing user with given unique_id
client.user.update()Updates an existing user’s information
client.user.delete()Deletes an existing user

​
For Package Developers

​
Environment Configuration

For testing the SDK, set these environment variables:
  • SIREN_API_KEY: Your API key from the Siren dashboard
  • SIREN_ENV: Set to dev for development/testing (defaults to prod)

​
Prerequisites

​
Setup Steps

  1. Clone the repository: 
    git clone https://github.com/KeyValueSoftwareSystems/siren-py-sdk.git
cd siren-py-sdk
  2. Create a virtual environment using uv: 
    uv venv
  3. Activate the virtual environment: 
    # On macOS/Linux
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
  4. Install dependencies with uv: 
    uv pip install -e ".[dev]"
  5. Set up pre-commit hooks: 
    uv run pre-commit install
You are now ready to contribute to the trysiren SDK!

​
Code Style & Linting

Code style is enforced by:
  • ruff (linting, formatting, import sorting)
  • pyright (type checking)
These tools are automatically run via pre-commit hooks.

​
Running Tests

To run the test suite, use the following command from the project root directory: 
uv run pytest
This will execute all tests defined in the tests/ directory.

​
Submitting Changes

  1. Create a feature branch for your changes
  2. Commit your changes (pre-commit hooks will run)
  3. Push your branch and open a Pull Request against the develop branch

​
Changes Planned

  • Investigate how critical .close() is for async client
  • Explore ways to avoid manual .close() calls