Audiences

The Konigle SDK provides audience segment management for creating targeted contact groups based on tags. Audiences enable marketers to segment contacts for targeted email campaigns and other marketing activities.

Creating Audiences

Basic Audience

import konigle
from konigle.models.comm import AudienceCreate

client = konigle.Client(api_key="your-api-key")

# Create an audience with auto-generated code
audience_data = AudienceCreate(
    name="Newsletter Subscribers",
    description="All contacts subscribed to our newsletter",
    tags=["newsletter", "active"]
)

audience = client.audiences.create(audience_data)
print(audience.model_dump_json(indent=2))

Audience with Custom Code

# Create audience with specific code
audience_data = AudienceCreate(
    name="Premium Customers",
    code="premium-customers",
    description="High-value customers with LTV > $1000",
    tags=["premium", "customer", "high-value"]
)

audience = client.audiences.create(audience_data)
print(audience.model_dump_json(indent=2))

Listing Audiences

from konigle.filters.comm import AudienceFilters

# List all audiences with pagination
audiences = client.audiences.list(page=1, page_size=20)

print(f"Total audiences: {audiences.count}")
for audience in audiences.payload:
    print(f"- {audience.name} (Code: {audience.code})")
    print(f"  Tags: {', '.join(audience.tags)}")
    print(f"  Description: {audience.description}")

# Search by name
search_filters = AudienceFilters(
    q="newsletter",
    ordering="-created_at"
)

results = client.audiences.list(filters=search_filters)
print(f"Found {results.count} audiences matching 'newsletter'")

# Filter by tags
tag_filters = AudienceFilters(
    tags="premium,customer"
)

premium_audiences = client.audiences.list(filters=tag_filters)
print(f"Found {premium_audiences.count} audiences with premium tags")

Getting a Specific Audience

# Get audience by ID
audience = client.audiences.get("audience_123456789")
print(audience.model_dump_json(indent=2))

Updating Audiences

from konigle.models.comm import AudienceUpdate

# Update audience information
update_data = AudienceUpdate(
    name="Active Newsletter Subscribers",
    description="Engaged newsletter subscribers with opens in last 30 days",
    tags=["newsletter", "active", "engaged"]
)

updated_audience = client.audiences.update(
    "audience_123456789",
    update_data
)
print(f"Updated audience: {updated_audience.name}")

# Update specific fields only
partial_update = AudienceUpdate(
    description="Updated description only"
)
audience = client.audiences.update("audience_123456789", partial_update)

# Update tags
tag_update = AudienceUpdate(
    tags=["newsletter", "premium", "engaged", "recent"]
)
audience = client.audiences.update("audience_123456789", tag_update)

Deleting Audiences

# Delete an audience
success = client.audiences.delete("audience_123456789")
if success:
    print("Audience deleted successfully")
else:
    print("Failed to delete audience")

Async Operations

import asyncio
import konigle
from konigle.models.comm import AudienceCreate

async def manage_audiences():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create audience
        audience_data = AudienceCreate(
            name="Async Test Audience",
            code="async-test",
            description="Test audience for async operations",
            tags=["test", "async"]
        )
        audience = await client.audiences.create(audience_data)

        # List audiences
        from konigle.filters.comm import AudienceFilters
        filters = AudienceFilters(q="async")
        audiences = await client.audiences.list(filters=filters)

        # Update audience
        from konigle.models.comm import AudienceUpdate
        update_data = AudienceUpdate(
            description="Updated async audience"
        )
        updated_audience = await client.audiences.update(
            audience.id,
            update_data
        )

        # Delete audience
        await client.audiences.delete(audience.id)

asyncio.run(manage_audiences())

CLI Commands

The Konigle CLI provides comprehensive audience management commands.

Audience Creation

# Create an audience with auto-generated code
konigle comm audiences create \
    --name "Newsletter Subscribers" \
    --description "All contacts subscribed to our newsletter" \
    --tag "newsletter" \
    --tag "active"

# Create audience with custom code
konigle comm audiences create \
    --name "Premium Customers" \
    --code "premium-customers" \
    --description "High-value customers" \
    --tag "premium" \
    --tag "customer" \
    --tag "high-value"

Audience Listing

# List all audiences
konigle comm audiences list

# List with pagination
konigle comm audiences list --page 2 --page-size 5

# Search by name
konigle comm audiences list --search "newsletter"

# Filter by tags
konigle comm audiences list --tags "premium,customer"

Audience Details

# Get specific audience details
konigle comm audiences get audience_123456789

Audience Updates

# Update audience name and description
konigle comm audiences update audience_123456789 \
    --name "Active Newsletter Subscribers" \
    --description "Engaged subscribers"

# Update audience code
konigle comm audiences update audience_123456789 \
    --code "active-newsletter"

# Update tags
konigle comm audiences update audience_123456789 \
    --tag "newsletter" \
    --tag "active" \
    --tag "engaged"

Audience Deletion

# Delete audience with confirmation
konigle comm audiences delete audience_123456789

# Delete audience without confirmation
konigle comm audiences delete audience_123456789 --yes