### Send a Message with Courier Python SDK

Source: https://github.com/trycourier/courier-python/blob/main/README.md

Quick start example demonstrating how to send a basic message using the synchronous Courier client. The client automatically reads the COURIER_API_KEY from your environment.

```python
from courier import Courier

client = Courier()

response = client.send.message(
    message={
        "to": {"email": "you@example.com"},
        "content": {
            "title": "Hello from Courier!",
            "body": "Your first notification, sent with the Python SDK.",
        },
    },
)

print(response.request_id)
```

--------------------------------

### Add and Execute Example Script

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Add your custom example code to `examples/<your-example>.py`, make it executable, and then run it against your API.

```py
# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
…
```

```sh
chmod +x examples/<your-example>.py
# run the example against your api
./examples/<your-example>.py
```

--------------------------------

### Install Python Package from Wheel File

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Install the Courier Python package efficiently using the generated wheel file after building from source.

```sh
pip install ./path-to-wheel-file.whl
```

--------------------------------

### Install Courier Python SDK

Source: https://github.com/trycourier/courier-python/blob/main/README.md

Install the Courier Python SDK using pip. This command adds the necessary package to your project.

```bash
pip install trycourier
```

--------------------------------

### Install Python Package from Git

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Install the Courier Python package directly from its Git repository using pip.

```sh
pip install git+ssh://git@github.com/trycourier/courier-python.git
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

If not using Rye, ensure the correct Python version is set and use this command to install development dependencies with pip.

```sh
pip install -r requirements-dev.lock
```

--------------------------------

### GET /lists

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Lists all subscription lists.

```APIDOC
## GET /lists

### Description
Lists all subscription lists.

### Method
GET

### Endpoint
/lists

### Response
#### Success Response (200)
- **ListListResponse** (object) - The response object containing the list of subscription lists.
```

--------------------------------

### Sync Dependencies with Rye

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Manually install Rye and then use this command to synchronize all project dependencies and features.

```sh
rye sync --all-features
```

--------------------------------

### GET /notifications

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Lists all notification templates.

```APIDOC
## GET /notifications

### Description
Lists all notification templates.

### Method
GET

### Endpoint
/notifications

### Response
#### Success Response (200)
- **NotificationListResponse** (object) - A list of notification templates.
```

--------------------------------

### GET /tenants/{tenant_id}/templates/{template_id}/versions/{version}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves a specific version of a template associated with a tenant.

```APIDOC
## GET /tenants/{tenant_id}/templates/{template_id}/versions/{version}

### Description
Retrieves a specific version of a template associated with a tenant.

### Method
GET

### Endpoint
/tenants/{tenant_id}/templates/{template_id}/versions/{version}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.
- **template_id** (string) - Required - The ID of the template.
- **version** (string) - Required - The version identifier.

### Response
#### Success Response (200)
- **BaseTemplateTenantAssociation** (object) - The template version details.
```

--------------------------------

### GET /messages

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Lists messages based on provided parameters.

```APIDOC
## GET /messages

### Description
Lists messages based on provided parameters.

### Method
GET

### Endpoint
/messages

### Parameters
#### Query Parameters
- **params** (object) - Optional - Additional filtering parameters.
```

--------------------------------

### Send a Message Asynchronously with Courier Python SDK

Source: https://github.com/trycourier/courier-python/blob/main/README.md

Example of sending a message using the asynchronous Courier client. Ensure you import `AsyncCourier` and use `await` for asynchronous operations.

```python
import asyncio
from courier import AsyncCourier

client = AsyncCourier()

async def main():
    response = await client.send.message(
        message={
            "to": {"email": "you@example.com"},
            "content": {
                "title": "Hello from Courier!",
                "body": "Sent from the async Python client.",
            },
        },
    )
    print(response.request_id)

asyncio.run(main())
```

--------------------------------

### GET /notifications/{id}/versions

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Lists the versions of a specific notification template.

```APIDOC
## GET /notifications/{id}/versions

### Description
Lists the versions of a specific notification template.

### Method
GET

### Endpoint
/notifications/{id}/versions

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the notification template.

### Response
#### Success Response (200)
- **NotificationTemplateVersionListResponse** (object) - A list of versions for the template.
```

--------------------------------

### GET /notifications/{id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves a specific notification template by its ID.

```APIDOC
## GET /notifications/{id}

### Description
Retrieves a specific notification template by its ID.

### Method
GET

### Endpoint
/notifications/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the notification template.

### Response
#### Success Response (200)
- **NotificationTemplateResponse** (object) - The requested notification template.
```

--------------------------------

### GET /lists/{list_id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves a specific subscription list.

```APIDOC
## GET /lists/{list_id}

### Description
Retrieves a specific subscription list.

### Method
GET

### Endpoint
/lists/{list_id}

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.

### Response
#### Success Response (200)
- **SubscriptionList** (object) - The subscription list details.
```

--------------------------------

### GET /bulk/{job_id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves details of a specific bulk job.

```APIDOC
## GET /bulk/{job_id}

### Description
Retrieves details of a specific bulk job.

### Method
GET

### Endpoint
/bulk/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the bulk job.

### Response
#### Success Response (200)
- **BulkRetrieveJobResponse** (object) - The response object containing job details.
```

--------------------------------

### Get Message Output

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Use this method to retrieve the output content of a specific message.

```python
client.messages.content(message_id)
```

--------------------------------

### GET /lists/{list_id}/subscriptions

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Lists subscriptions for a specific list.

```APIDOC
## GET /lists/{list_id}/subscriptions

### Description
Lists subscriptions for a specific list.

### Method
GET

### Endpoint
/lists/{list_id}/subscriptions

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.

### Response
#### Success Response (200)
- **SubscriptionListResponse** (object) - The response object containing subscriptions.
```

--------------------------------

### GET /messages/{message_id}/output

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves the content of a specific message.

```APIDOC
## GET /messages/{message_id}/output

### Description
Retrieves the content of a specific message.

### Method
GET

### Endpoint
/messages/{message_id}/output

### Parameters
#### Path Parameters
- **message_id** (string) - Required - The unique identifier of the message.
```

--------------------------------

### GET /bulk/{job_id}/users

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Lists users associated with a specific bulk job.

```APIDOC
## GET /bulk/{job_id}/users

### Description
Lists users associated with a specific bulk job.

### Method
GET

### Endpoint
/bulk/{job_id}/users

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the bulk job.

### Response
#### Success Response (200)
- **BulkListUsersResponse** (object) - The response object containing the list of users.
```

--------------------------------

### GET /notifications/{id}/content

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves the content of a specific notification template.

```APIDOC
## GET /notifications/{id}/content

### Description
Retrieves the content of a specific notification template.

### Method
GET

### Endpoint
/notifications/{id}/content

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the notification template.

### Response
#### Success Response (200)
- **NotificationRetrieveContentResponse** (object) - The content of the notification template.
```

--------------------------------

### GET /messages/{message_id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves the details of a specific message by its ID.

```APIDOC
## GET /messages/{message_id}

### Description
Retrieves the details of a specific message by its ID.

### Method
GET

### Endpoint
/messages/{message_id}

### Parameters
#### Path Parameters
- **message_id** (string) - Required - The unique identifier of the message.
```

--------------------------------

### Initialize Courier Client

Source: https://github.com/trycourier/courier-python/blob/main/AGENTS.md

Instantiate the Courier client. It automatically reads the COURIER_API_KEY from environment variables.

```python
from courier import Courier

client = Courier()  # reads COURIER_API_KEY from env
```

--------------------------------

### Bootstrap Project Environment with Rye

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Run this script to automatically provision a Python environment with the expected Python version using Rye.

```sh
./scripts/bootstrap
```

--------------------------------

### Initialize Courier Client

Source: https://context7.com/trycourier/courier-python/llms.txt

Initialize the Courier client using environment variables or explicit configuration. Supports both synchronous and asynchronous clients.

```python
from courier import Courier, AsyncCourier

# Auto-reads COURIER_API_KEY from environment
client = Courier()

# Explicit API key with custom options
client = Courier(
    api_key="your-api-key",
    timeout=30.0,
    max_retries=3,
)

# Async client for asyncio applications
async_client = AsyncCourier(api_key="your-api-key")
```

--------------------------------

### Manage Tenant Templates

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Methods for retrieving, listing, publishing, and replacing tenant templates.

```python
client.tenants.templates.retrieve(template_id, *, tenant_id)
```

```python
client.tenants.templates.list(tenant_id, **params)
```

```python
client.tenants.templates.publish(template_id, *, tenant_id, **params)
```

```python
client.tenants.templates.replace(template_id, *, tenant_id, **params)
```

--------------------------------

### Manage Brand Configurations

Source: https://context7.com/trycourier/courier-python/llms.txt

Create, retrieve, update, list, and delete brand settings for notification styling.

```python
from courier import Courier

client = Courier()

# Create a brand
brand = client.brands.create(
    name="Acme Brand",
    settings={
        "colors": {
            "primary": "#0066CC",
            "secondary": "#333333",
        },
        "email": {
            "header": {
                "logo": {
                    "href": "https://example.com",
                    "image": "https://example.com/logo.png",
                },
            },
            "footer": {
                "content": "© 2024 Acme Inc. All rights reserved.",
            },
        },
    },
)
print(f"Brand ID: {brand.id}")

# Retrieve a brand
brand = client.brands.retrieve("brand_id")
print(f"Brand: {brand.name}")

# Update a brand
updated = client.brands.update(
    "brand_id",
    name="Acme Brand Updated",
)

# List all brands
brands = client.brands.list()
for b in brands.results:
    print(f"Brand: {b.id} - {b.name}")

# Delete a brand
client.brands.delete("brand_id")
```

--------------------------------

### Build Python Package

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Create a distributable version of the library by building the source. This generates `.tar.gz` and `.whl` files in the `dist/` directory.

```sh
rye build
```

```sh
python -m build
```

--------------------------------

### GET /messages/{message_id}/history

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves the history of a specific message.

```APIDOC
## GET /messages/{message_id}/history

### Description
Retrieves the history of a specific message.

### Method
GET

### Endpoint
/messages/{message_id}/history

### Parameters
#### Path Parameters
- **message_id** (string) - Required - The unique identifier of the message.
#### Query Parameters
- **params** (object) - Optional - Additional filtering parameters.
```

--------------------------------

### Run Project Tests

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Execute the project's test suite using the provided script.

```sh
./scripts/test
```

--------------------------------

### Invoke and List Automations

Source: https://context7.com/trycourier/courier-python/llms.txt

Use automation templates or define ad-hoc workflows with custom steps. Requires a configured Courier client instance.

```python
from courier import Courier

client = Courier()

# Invoke an automation template
response = client.automations.invoke.invoke_by_template(
    "welcome-sequence",
    recipient="user_123",
    data={
        "name": "Jane",
        "signup_date": "2024-01-15",
    },
    profile={
        "email": "jane@example.com",
    },
)
print(f"Run ID: {response.run_id}")

# Invoke an ad-hoc automation with custom steps
response = client.automations.invoke.invoke_ad_hoc(
    automation={
        "steps": [
            {
                "action": "send",
                "message": {
                    "template": "WELCOME_EMAIL",
                },
            },
            {
                "action": "delay",
                "duration": "1 day",
            },
            {
                "action": "send",
                "message": {
                    "template": "FOLLOW_UP_EMAIL",
                },
            },
        ],
    },
    recipient="user_123",
    data={"name": "Jane"},
)
print(f"Automation run: {response.run_id}")

# List automation templates
templates = client.automations.list()
for template in templates.items:
    print(f"Template: {template.id} - {template.name}")
```

--------------------------------

### POST /bulk

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Creates a new bulk job.

```APIDOC
## POST /bulk

### Description
Creates a new bulk job.

### Method
POST

### Endpoint
/bulk

### Response
#### Success Response (200)
- **BulkCreateJobResponse** (object) - The response object containing job details.
```

--------------------------------

### Publish to PyPI Manually

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Manually release a package to PyPI by running the `bin/publish-pypi` script with a `PYPI_TOKEN` set in the environment.

```sh
bin/publish-pypi
```

--------------------------------

### Manage User Profiles

Source: https://context7.com/trycourier/courier-python/llms.txt

Create, update, and retrieve user profile information.

```python
from courier import Courier

client = Courier()

# Create or merge a user profile
response = client.profiles.create(
    "user_123",
    profile={
        "email": "jane@example.com",
        "phone_number": "+15551234567",
        "name": "Jane Doe",
        "custom": {
            "plan": "premium",
            "signup_date": "2024-01-15",
        },
    },
)
print(f"Profile status: {response.status}")

# Retrieve a user profile
profile = client.profiles.retrieve("user_123")
print(f"Email: {profile.profile.get('email')}")
```

--------------------------------

### Create or Update User Profile with Courier Python SDK

Source: https://github.com/trycourier/courier-python/blob/main/README.md

Create or update a user profile, including their email and name, using the Courier client.

```python
# Create or update a user profile
client.profiles.create("user_123", profile={
    "email": "jane@example.com",
    "name": "Jane Doe",
})
```

--------------------------------

### Format Project Code

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Automatically format the code and fix ruff issues using the provided script.

```sh
./scripts/format
```

--------------------------------

### Get Message History

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Use this method to retrieve the history of a specific message, with optional parameters.

```python
client.messages.history(message_id, **params)
```

--------------------------------

### Manage Tenants

Source: https://context7.com/trycourier/courier-python/llms.txt

Organize users and templates by tenant. Supports CRUD operations and listing users within a tenant.

```python
from courier import Courier

client = Courier()

# Create or update a tenant
tenant = client.tenants.update(
    "tenant_acme",
    name="Acme Corporation",
    default_preferences={
        "items": [
            {
                "id": "marketing",
                "status": "OPTED_IN",
            },
        ],
    },
)
print(f"Tenant: {tenant.id}")

# Retrieve a tenant
tenant = client.tenants.retrieve("tenant_acme")
print(f"Tenant name: {tenant.name}")

# List all tenants
tenants = client.tenants.list()
for t in tenants.items:
    print(f"Tenant: {t.id}")

# List users in a tenant
users = client.tenants.list_users("tenant_acme")
for user in users.items:
    print(f"User: {user.user_id}")

# Delete a tenant
client.tenants.delete("tenant_acme")
```

--------------------------------

### Import Tenant Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Required imports for tenant-related data structures.

```python
from courier.types import (
    BaseTemplateTenantAssociation,
    DefaultPreferences,
    PostTenantTemplatePublishRequest,
    PostTenantTemplatePublishResponse,
    PutTenantTemplateRequest,
    PutTenantTemplateResponse,
    SubscriptionTopicNew,
    Tenant,
    TenantAssociation,
    TenantTemplateInput,
    TenantListResponse,
    TenantListUsersResponse,
)
```

--------------------------------

### Lint Project Code

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Run the linting process to check for code style and potential issues using ruff.

```sh
./scripts/lint
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/trycourier/courier-python/blob/main/CONTRIBUTING.md

Activate the virtual environment to omit the `rye run` prefix when executing Python scripts.

```sh
source .venv/bin/activate
```

--------------------------------

### Tenant Templates API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Manage templates within a tenant.

```APIDOC
## GET /tenants/{tenant_id}/templates/{template_id}

### Description
Retrieves a specific template within a tenant.

### Method
GET

### Endpoint
/tenants/{tenant_id}/templates/{template_id}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.
- **template_id** (string) - Required - The ID of the template.

### Response
#### Success Response (200)
- **BaseTemplateTenantAssociation** (object) - The template association object.

## GET /tenants/{tenant_id}/templates

### Description
Retrieves a list of templates within a tenant.

### Method
GET

### Endpoint
/tenants/{tenant_id}/templates

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.

#### Query Parameters
- **params** (object) - Optional - Parameters for filtering the list of templates.

### Response
#### Success Response (200)
- **TemplateListResponse** (object) - The response object containing a list of templates.

## POST /tenants/{tenant_id}/templates/{template_id}/publish

### Description
Publishes a template within a tenant.

### Method
POST

### Endpoint
/tenants/{tenant_id}/templates/{template_id}/publish

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.
- **template_id** (string) - Required - The ID of the template.

#### Request Body
- **params** (object) - Required - Parameters for publishing the template.

### Response
#### Success Response (200)
- **PostTenantTemplatePublishResponse** (object) - The response object confirming the publish action.

## PUT /tenants/{tenant_id}/templates/{template_id}

### Description
Replaces an existing template within a tenant.

### Method
PUT

### Endpoint
/tenants/{tenant_id}/templates/{template_id}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.
- **template_id** (string) - Required - The ID of the template.

#### Request Body
- **params** (object) - Required - The updated template data.

### Response
#### Success Response (200)
- **PutTenantTemplateResponse** (object) - The response object containing the updated template data.
```

--------------------------------

### POST /bulk/{job_id}/run

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Runs a specific bulk job.

```APIDOC
## POST /bulk/{job_id}/run

### Description
Runs a specific bulk job.

### Method
POST

### Endpoint
/bulk/{job_id}/run

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the bulk job.
```

--------------------------------

### Import Profile Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Import types for profile creation, retrieval, and replacement operations.

```python
from courier.types import (
    SubscribeToListsRequestItem,
    ProfileCreateResponse,
    ProfileRetrieveResponse,
    ProfileReplaceResponse,
)
```

--------------------------------

### POST /routing-strategies

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Creates a new routing strategy.

```APIDOC
## POST /routing-strategies

### Description
Creates a new routing strategy configuration.

### Method
POST

### Endpoint
/routing-strategies

### Response
#### Success Response (200)
- **RoutingStrategyGetResponse** (object) - The created routing strategy details
```

--------------------------------

### POST /profiles/{user_id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Creates or updates a user profile.

```APIDOC
## POST /profiles/{user_id}

### Description
Creates a profile for a specific user.

### Method
POST

### Endpoint
/profiles/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The unique identifier for the user

### Response
#### Success Response (200)
- **ProfileCreateResponse** (object) - The created profile response
```

--------------------------------

### Manage Tenant Preferences

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Methods for updating or deleting default preference items for a specific tenant.

```python
client.tenants.preferences.items.update(topic_id, *, tenant_id, **params)
```

```python
client.tenants.preferences.items.delete(topic_id, *, tenant_id)
```

--------------------------------

### POST /notifications

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Creates a new notification template.

```APIDOC
## POST /notifications

### Description
Creates a new notification template.

### Method
POST

### Endpoint
/notifications

### Response
#### Success Response (200)
- **NotificationTemplateResponse** (object) - The created notification template.
```

--------------------------------

### Run a Bulk Messaging Job

Source: https://context7.com/trycourier/courier-python/llms.txt

Initiates the sending of notifications for a completed bulk job. Ensure all users have been added before running.

```python
# Run the bulk job to send messages
client.bulk.run_job(job_id)
```

--------------------------------

### Tenants API

Source: https://context7.com/trycourier/courier-python/llms.txt

Endpoints for managing multi-tenant configurations, including creating, retrieving, listing, and managing users within a tenant.

```APIDOC
## PUT /tenants/{tenant_id}

### Description
Create or update a tenant configuration.

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The unique identifier for the tenant.

### Request Body
- **name** (string) - Required - The name of the tenant.
- **default_preferences** (object) - Optional - Default notification preferences for the tenant.
```

--------------------------------

### Tenant Preferences Items API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Manage default preferences for items within a tenant.

```APIDOC
## PUT /tenants/{tenant_id}/default_preferences/items/{topic_id}

### Description
Updates the default preferences for a specific item (topic) within a tenant.

### Method
PUT

### Endpoint
/tenants/{tenant_id}/default_preferences/items/{topic_id}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.
- **topic_id** (string) - Required - The ID of the topic.

#### Request Body
- **params** (object) - Required - The updated preference data.

### Response
#### Success Response (200)
- **None**

## DELETE /tenants/{tenant_id}/default_preferences/items/{topic_id}

### Description
Deletes the default preferences for a specific item (topic) within a tenant.

### Method
DELETE

### Endpoint
/tenants/{tenant_id}/default_preferences/items/{topic_id}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.
- **topic_id** (string) - Required - The ID of the topic.

### Response
#### Success Response (200)
- **None**
```

--------------------------------

### Manage Profile Lists

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Methods for retrieving, deleting, and subscribing to profile lists.

```python
client.profiles.lists.retrieve(user_id, **params)
```

```python
client.profiles.lists.delete(user_id)
```

```python
client.profiles.lists.subscribe(user_id, **params)
```

--------------------------------

### Authentication API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Handle authentication and token issuance.

```APIDOC
## POST /auth/issue-token

### Description
Issues an authentication token.

### Method
POST

### Endpoint
/auth/issue-token

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for issuing the token.

### Response
#### Success Response (200)
- **AuthIssueTokenResponse** (object) - The response containing the issued token.

#### Response Example
```json
{
  "token": "your_auth_token"
}
```
```

--------------------------------

### Create Notification

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Use this method to create a new notification. It returns a NotificationTemplateResponse object.

```python
client.notifications.create(**params) -> NotificationTemplateResponse
```

--------------------------------

### Subscribe a User to a List

Source: https://context7.com/trycourier/courier-python/llms.txt

Adds a single user to a specified subscriber list.

```python
# Subscribe a user to a list
client.lists.subscriptions.subscribe_user(
    "user_123",
    list_id="newsletter-subscribers",
)
```

--------------------------------

### Manage Push Notification Tokens

Source: https://context7.com/trycourier/courier-python/llms.txt

Add, list, retrieve, and delete device tokens for push notifications.

```python
from courier import Courier

client = Courier()

# Add a push token for a user
client.users.tokens.add_single(
    "user_123",
    token="device_token_abc123",
    provider_key="firebase-fcm",
    device={
        "app_id": "com.example.app",
        "platform": "android",
    },
)

# List all tokens for a user
tokens = client.users.tokens.list("user_123")
for token in tokens.tokens:
    print(f"Token: {token.token} ({token.provider_key})")

# Retrieve a specific token
token = client.users.tokens.retrieve("user_123", token="device_token_abc123")
print(f"Provider: {token.provider_key}")

# Delete a token
client.users.tokens.delete("user_123", token="device_token_abc123")
```

--------------------------------

### Send a Message

Source: https://github.com/trycourier/courier-python/blob/main/AGENTS.md

Send a message to a user via specified channels. Use 'routing.method: "single"' for sequential delivery or '"all"' for parallel delivery.

```python
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "TEMPLATE_ID",
        "data": {"order_id": "456"},
        "routing": {"method": "single", "channels": ["email", "sms"]},
    },
)

print(response.request_id)
```

--------------------------------

### Import Subscription List Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Imports the response type for subscription list operations.

```python
from courier.types.lists import SubscriptionListResponse
```

--------------------------------

### List Subscriber Lists with Pattern Filtering

Source: https://context7.com/trycourier/courier-python/llms.txt

Retrieves a list of all subscriber lists, with optional pattern filtering to find specific lists.

```python
# List all lists with pattern filtering
all_lists = client.lists.list(pattern="newsletter-**")
for lst in all_lists.items:
    print(f"List: {lst.id}")
```

--------------------------------

### Import Template Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Required import for template list responses.

```python
from courier.types.tenants import TemplateListResponse
```

--------------------------------

### POST /bulk/{job_id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Adds users to a specific bulk job.

```APIDOC
## POST /bulk/{job_id}

### Description
Adds users to a specific bulk job.

### Method
POST

### Endpoint
/bulk/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the bulk job.
```

--------------------------------

### Import Inbound Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Imports the response type for inbound tracking events.

```python
from courier.types import InboundTrackEventResponse
```

--------------------------------

### Import Bulk Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Imports necessary types for interacting with the Bulk API.

```python
from courier.types import (
    InboundBulkMessage,
    InboundBulkMessageUser,
    BulkCreateJobResponse,
    BulkListUsersResponse,
    BulkRetrieveJobResponse,
)
```

--------------------------------

### List Subscriptions for a List

Source: https://context7.com/trycourier/courier-python/llms.txt

Retrieves all subscribers currently in a specific list.

```python
# List subscriptions for a list
subscriptions = client.lists.subscriptions.list("newsletter-subscribers")
for sub in subscriptions.items:
    print(f"Subscriber: {sub.recipient_id}")
```

--------------------------------

### Import List Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Imports types required for managing subscription lists.

```python
from courier.types import PutSubscriptionsRecipient, SubscriptionList, ListListResponse
```

--------------------------------

### Import Notification Check Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Import necessary types for handling notification check responses.

```python
from courier.types.notifications import CheckUpdateResponse, CheckListResponse
```

--------------------------------

### Brands API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Manage brand configurations.

```APIDOC
## POST /brands

### Description
Creates a new brand.

### Method
POST

### Endpoint
/brands

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating the brand.

### Response
#### Success Response (200)
- **Brand** (object) - The newly created brand details.

#### Response Example
```json
{
  "id": "brand_id_1",
  "name": "My Brand"
}
```
```

```APIDOC
## GET /brands/{brand_id}

### Description
Retrieves a specific brand by its ID.

### Method
GET

### Endpoint
/brands/{brand_id}

### Parameters
#### Path Parameters
- **brand_id** (string) - Required - The ID of the brand to retrieve.

### Response
#### Success Response (200)
- **Brand** (object) - The brand details.

#### Response Example
```json
{
  "id": "brand_id_1",
  "name": "My Brand"
}
```
```

```APIDOC
## PUT /brands/{brand_id}

### Description
Updates an existing brand.

### Method
PUT

### Endpoint
/brands/{brand_id}

### Parameters
#### Path Parameters
- **brand_id** (string) - Required - The ID of the brand to update.
#### Request Body
- **params** (object) - Required - Parameters for updating the brand.

### Response
#### Success Response (200)
- **Brand** (object) - The updated brand details.

#### Response Example
```json
{
  "id": "brand_id_1",
  "name": "Updated Brand Name"
}
```
```

```APIDOC
## GET /brands

### Description
Retrieves a list of brands.

### Method
GET

### Endpoint
/brands

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering and pagination.

### Response
#### Success Response (200)
- **BrandListResponse** (object) - The response containing a list of brands.

#### Response Example
```json
{
  "items": [
    {
      "id": "brand_id_1",
      "name": "My Brand"
    }
  ]
}
```
```

```APIDOC
## DELETE /brands/{brand_id}

### Description
Deletes a brand by its ID.

### Method
DELETE

### Endpoint
/brands/{brand_id}

### Parameters
#### Path Parameters
- **brand_id** (string) - Required - The ID of the brand to delete.

### Response
#### Success Response (200)
- **None**

#### Response Example
```json
null
```
```

--------------------------------

### Import Notification Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Imports all necessary types for working with notifications from the courier.types module.

```python
from courier.types import (
    BaseCheck,
    Check,
    ElementWithChecksums,
    NotificationContentGetResponse,
    NotificationContentMutationResponse,
    NotificationContentPutRequest,
    NotificationElementPutRequest,
    NotificationGetContent,
    NotificationLocalePutRequest,
    NotificationTemplateCreateRequest,
    NotificationTemplatePayload,
    NotificationTemplatePublishRequest,
    NotificationTemplateResponse,
    NotificationTemplateState,
    NotificationTemplateSummary,
    NotificationTemplateUpdateRequest,
    NotificationTemplateVersionListResponse,
    VersionNode,
    NotificationListResponse,
    NotificationRetrieveContentResponse,
)
```

--------------------------------

### Create or Update a Subscriber List

Source: https://context7.com/trycourier/courier-python/llms.txt

Manages subscriber lists for group notifications. Use this to create new lists or update existing ones.

```python
from courier import Courier

client = Courier()

# Create or update a list
client.lists.update(
    "newsletter-subscribers",
    name="Newsletter Subscribers",
)
```

--------------------------------

### Tenants API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Manage tenant resources and their associated users.

```APIDOC
## GET /tenants/{tenant_id}

### Description
Retrieves a specific tenant by its ID.

### Method
GET

### Endpoint
/tenants/{tenant_id}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.

### Response
#### Success Response (200)
- **Tenant** (object) - The tenant object.

## PUT /tenants/{tenant_id}

### Description
Updates an existing tenant.

### Method
PUT

### Endpoint
/tenants/{tenant_id}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.

#### Request Body
- **params** (object) - Required - The updated tenant data.

### Response
#### Success Response (200)
- **Tenant** (object) - The updated tenant object.

## GET /tenants

### Description
Retrieves a list of tenants.

### Method
GET

### Endpoint
/tenants

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering the list of tenants.

### Response
#### Success Response (200)
- **TenantListResponse** (object) - The response object containing a list of tenants.

## DELETE /tenants/{tenant_id}

### Description
Deletes a tenant.

### Method
DELETE

### Endpoint
/tenants/{tenant_id}

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant to delete.

### Response
#### Success Response (200)
- **None**

## GET /tenants/{tenant_id}/users

### Description
Retrieves a list of users associated with a specific tenant.

### Method
GET

### Endpoint
/tenants/{tenant_id}/users

### Parameters
#### Path Parameters
- **tenant_id** (string) - Required - The ID of the tenant.

#### Query Parameters
- **params** (object) - Optional - Parameters for filtering the list of users.

### Response
#### Success Response (200)
- **TenantListUsersResponse** (object) - The response object containing a list of users for the tenant.
```

--------------------------------

### Create a Bulk Messaging Job

Source: https://context7.com/trycourier/courier-python/llms.txt

Initiates a bulk messaging job to send notifications to a large number of recipients efficiently. Returns a job ID for subsequent operations.

```python
from courier import Courier

client = Courier()

# Create a bulk job
job = client.bulk.create_job(
    message={
        "event": "WELCOME_NOTIFICATION",
        "data": {
            "company_name": "Acme Inc",
        },
    }
)
job_id = job.job_id
print(f"Created job: {job_id}")
```

--------------------------------

### Import Message Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Import necessary types for message-related operations.

```python
from courier.types import (
    MessageDetails,
    MessageRetrieveResponse,
    MessageListResponse,
    MessageContentResponse,
    MessageHistoryResponse,
)
```

--------------------------------

### Manage User Preferences

Source: https://context7.com/trycourier/courier-python/llms.txt

Retrieve and update notification preferences for users at the topic or category level.

```python
from courier import Courier

client = Courier()

# Get all preferences for a user
prefs = client.users.preferences.retrieve("user_123")
for item in prefs.items:
    print(f"Topic {item.topic_id}: {item.status}")

# Get preference for a specific topic
topic_pref = client.users.preferences.retrieve_topic("user_123", topic_id="marketing")
print(f"Marketing: {topic_pref.status}")

# Update or create a topic preference
result = client.users.preferences.update_or_create_topic(
    "user_123",
    topic_id="marketing",
    status="OPTED_OUT",
)
print(f"Updated: {result.message}")
```

--------------------------------

### Automations API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Manage and invoke automations.

```APIDOC
## GET /automations

### Description
Retrieves a list of automations.

### Method
GET

### Endpoint
/automations

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering and pagination.

### Response
#### Success Response (200)
- **AutomationTemplateListResponse** (object) - The response containing a list of automation templates.

#### Response Example
```json
{
  "items": [
    {
      "id": "automation_id_1",
      "name": "Welcome Email Automation"
    }
  ]
}
```
```

```APIDOC
## POST /automations/invoke

### Description
Invokes an ad-hoc automation.

### Method
POST

### Endpoint
/automations/invoke

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for invoking the ad-hoc automation.

### Response
#### Success Response (200)
- **AutomationInvokeResponse** (object) - The response indicating the automation invocation status.

#### Response Example
```json
{
  "message": "Automation invoked successfully."
}
```
```

```APIDOC
## POST /automations/{templateId}/invoke

### Description
Invokes an automation by its template ID.

### Method
POST

### Endpoint
/automations/{templateId}/invoke

### Parameters
#### Path Parameters
- **template_id** (string) - Required - The ID of the automation template to invoke.
#### Request Body
- **params** (object) - Required - Parameters for invoking the automation.

### Response
#### Success Response (200)
- **AutomationInvokeResponse** (object) - The response indicating the automation invocation status.

#### Response Example
```json
{
  "message": "Automation invoked successfully."
}
```
```

--------------------------------

### Import List Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Required imports for handling list-related responses in the Courier SDK.

```python
from courier.types.profiles import ListRetrieveResponse, ListDeleteResponse, ListSubscribeResponse
```

--------------------------------

### PUT /notifications/{id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Replaces an existing notification template.

```APIDOC
## PUT /notifications/{id}

### Description
Replaces an existing notification template.

### Method
PUT

### Endpoint
/notifications/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the notification template.

### Response
#### Success Response (200)
- **NotificationTemplateResponse** (object) - The updated notification template.
```

--------------------------------

### List Users in a Bulk Job

Source: https://context7.com/trycourier/courier-python/llms.txt

Retrieves a list of all recipients added to a specific bulk job.

```python
# List users in the job
users = client.bulk.list_users(job_id)
for user in users.items:
    print(f"User: {user.recipient}")
```

--------------------------------

### Profiles Lists API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Manage user lists within profiles.

```APIDOC
## GET /profiles/{user_id}/lists

### Description
Retrieves a list of items associated with a user profile.

### Method
GET

### Endpoint
/profiles/{user_id}/lists

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for retrieval.

### Response
#### Success Response (200)
- **ListRetrieveResponse** (object) - The response object containing the retrieved list data.

## DELETE /profiles/{user_id}/lists

### Description
Deletes a list associated with a user profile.

### Method
DELETE

### Endpoint
/profiles/{user_id}/lists

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.

### Response
#### Success Response (200)
- **ListDeleteResponse** (object) - The response object indicating the result of the deletion.

## POST /profiles/{user_id}/lists

### Description
Subscribes a user to a list within their profile.

### Method
POST

### Endpoint
/profiles/{user_id}/lists

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.

#### Request Body
- **params** (object) - Required - Parameters for the subscription.

### Response
#### Success Response (200)
- **ListSubscribeResponse** (object) - The response object confirming the subscription.
```

--------------------------------

### List Notification Versions

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Retrieves a list of all versions for a given notification ID. Supports optional parameters for filtering and returns a NotificationTemplateVersionListResponse object.

```python
client.notifications.list_versions(id, **params) -> NotificationTemplateVersionListResponse
```

--------------------------------

### POST /send

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Sends a message using the Courier platform.

```APIDOC
## POST /send

### Description
Sends a message through the Courier platform.

### Method
POST

### Endpoint
/send

### Response
#### Success Response (200)
- **SendMessageResponse** (object) - The response object containing details about the sent message.
```

--------------------------------

### PUT /lists/{list_id}/restore

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Restores a specific subscription list.

```APIDOC
## PUT /lists/{list_id}/restore

### Description
Restores a specific subscription list.

### Method
PUT

### Endpoint
/lists/{list_id}/restore

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.
```

--------------------------------

### User Preferences API

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Endpoints for managing user-specific notification preferences and topics.

```APIDOC
## GET /users/{user_id}/preferences

### Description
Retrieves the preferences for a specific user.

### Method
GET

### Endpoint
/users/{user_id}/preferences

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.

## GET /users/{user_id}/preferences/{topic_id}

### Description
Retrieves the preference for a specific topic for a user.

### Method
GET

### Endpoint
/users/{user_id}/preferences/{topic_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.
- **topic_id** (string) - Required - The ID of the topic.

## PUT /users/{user_id}/preferences/{topic_id}

### Description
Updates or creates a preference for a specific topic for a user.

### Method
PUT

### Endpoint
/users/{user_id}/preferences/{topic_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user.
- **topic_id** (string) - Required - The ID of the topic.
```

--------------------------------

### PUT /lists/{list_id}/subscriptions/{user_id}

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Subscribes a specific user to a list.

```APIDOC
## PUT /lists/{list_id}/subscriptions/{user_id}

### Description
Subscribes a specific user to a list.

### Method
PUT

### Endpoint
/lists/{list_id}/subscriptions/{user_id}

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.
- **user_id** (string) - Required - The ID of the user.
```

--------------------------------

### Import Routing Strategy Types

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Import types required for managing routing strategies and associated notifications.

```python
from courier.types import (
    AssociatedNotificationListResponse,
    RoutingStrategyCreateRequest,
    RoutingStrategyGetResponse,
    RoutingStrategyListResponse,
    RoutingStrategyReplaceRequest,
    RoutingStrategySummary,
)
```

--------------------------------

### Issue JWT Token for User Authentication

Source: https://context7.com/trycourier/courier-python/llms.txt

Generate JWT tokens for client-side SDK authentication. Specify scopes to grant granular permissions for user interactions.

```python
from courier import Courier

client = Courier()

# Issue a token for a specific user with inbox permissions
result = client.auth.issue_token(
    scope="user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences",
    expires_in="2 days",
)
print(f"Token: {result.token}")
```

```python
# Token for read-only brand access
result = client.auth.issue_token(
    scope="user_id:user_456 read:brands",
    expires_in="1h",
)
```

```python
# Token with multiple user scopes
result = client.auth.issue_token(
    scope="user_id:user_123 user_id:user_456 read:messages",
    expires_in="30m",
)
```

--------------------------------

### Add Users to a Bulk Job

Source: https://context7.com/trycourier/courier-python/llms.txt

Adds recipients to an existing bulk job. You can specify recipient details, profile information, and custom data for each user.

```python
# Add users to the bulk job
client.bulk.add_users(
    job_id,
    users=[
        {
            "recipient": "user_1",
            "profile": {"email": "user1@example.com"},
            "data": {"name": "User One"},
        },
        {
            "recipient": "user_2",
            "profile": {"email": "user2@example.com"},
            "data": {"name": "User Two"},
        },
        {
            "recipient": "user_3",
            "profile": {"email": "user3@example.com"},
            "data": {"name": "User Three"},
        },
    ],
)
```

--------------------------------

### PUT /lists/{list_id}/subscriptions

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Subscribes to a list.

```APIDOC
## PUT /lists/{list_id}/subscriptions

### Description
Subscribes to a list.

### Method
PUT

### Endpoint
/lists/{list_id}/subscriptions

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.
```

--------------------------------

### Retrieve a Subscriber List

Source: https://context7.com/trycourier/courier-python/llms.txt

Fetches details of a specific subscriber list by its ID.

```python
# Retrieve a list
subscription_list = client.lists.retrieve("newsletter-subscribers")
print(f"List: {subscription_list.name}")
```

--------------------------------

### User Tokens API

Source: https://context7.com/trycourier/courier-python/llms.txt

Endpoints for managing push notification device tokens for users.

```APIDOC
## POST /users/{user_id}/tokens

### Description
Add a push notification device token for a user.

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The unique identifier for the user.

### Request Body
- **token** (string) - Required - The device token.
- **provider_key** (string) - Required - The provider key (e.g., firebase-fcm).
- **device** (object) - Required - Device details including app_id and platform.
```

--------------------------------

### List All Audiences

Source: https://context7.com/trycourier/courier-python/llms.txt

Retrieves a list of all audience segments. Useful for auditing or managing existing segments.

```python
# List all audiences
audiences = client.audiences.list()
for aud in audiences.items:
    print(f"Audience: {aud.id} - {aud.name}")
```

--------------------------------

### POST /lists/{list_id}/subscriptions

Source: https://github.com/trycourier/courier-python/blob/main/api.md

Adds a subscription to a list.

```APIDOC
## POST /lists/{list_id}/subscriptions

### Description
Adds a subscription to a list.

### Method
POST

### Endpoint
/lists/{list_id}/subscriptions

### Parameters
#### Path Parameters
- **list_id** (string) - Required - The ID of the list.
```