Contacts

The Konigle SDK provides contact management for email marketing, enabling you to store customer information, track lifetime value, manage consent preferences, and organize contacts with tags for targeted campaigns.

Creating Contacts

Basic Contact

import konigle
from konigle.models.comm import ContactCreate, MarketingConsent

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

# Create a basic contact
contact_data = ContactCreate(
    email="customer@example.com",
    first_name="John",
    last_name="Doe",
    phone="+1234567890",
    country="United States",
    source="lead",
    tags=["newsletter", "blog-subscriber"]
)

contact = client.contacts.create(contact_data)
print(f"Created contact: {contact.id}")
print(f"Email: {contact.email}")
print(f"Name: {contact.first_name} {contact.last_name}")

Contact with Marketing Consent

Manage consent preferences for different marketing channels:

# Create contact with specific consent preferences
marketing_consent = MarketingConsent(
    email=True,
    sms=False,
    whatsapp=True
)

contact_data = ContactCreate(
    email="customer@example.com",
    first_name="Jane",
    last_name="Smith",
    source="purchase",
    tags=["customer", "premium"],
    marketing_consent=marketing_consent
)

contact = client.contacts.create(contact_data)
print(f"Email consent: {contact.marketing_consent.email}")
print(f"SMS consent: {contact.marketing_consent.sms}")
print(f"WhatsApp consent: {contact.marketing_consent.whatsapp}")

Listing Contacts

from konigle.filters.comm import ContactFilters

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

print(f"Total contacts: {contacts.count}")
for contact in contacts.payload:
    print(f"- {contact.email} ({contact.first_name} {contact.last_name})")
    print(f"  Source: {contact.source}")
    print(f"  Tags: {', '.join(contact.tags)}")
    if contact.ltv:
        print(f"  LTV: {contact.ltv} {contact.ltv_currency}")

# Filter by source
lead_filters = ContactFilters(
    source="lead",
    ordering="-created_at"
)

leads = client.contacts.list(filters=lead_filters)
print(f"Total leads: {leads.count}")

# Search by email
search_filters = ContactFilters(
    q="example.com"
)

contacts = client.contacts.list(filters=search_filters)

# Filter by tags
tag_filters = ContactFilters(
    tags="newsletter,premium"
)

tagged_contacts = client.contacts.list(filters=tag_filters)
print(f"Found {tagged_contacts.count} contacts with tags")

Getting a Specific Contact

# Get contact by ID
contact = client.contacts.get("contact_123456789")
print(f"Contact details:")
print(contact.model_dump_json(indent=4))

Updating Contacts

from konigle.models.comm import ContactUpdate, MarketingConsent

# Update contact information
update_data = ContactUpdate(
    first_name="Jonathan",
    phone="+1987654321",
    tags=["newsletter", "blog-subscriber", "premium"]
)

updated_contact = client.contacts.update("contact_123456789", update_data)
print(f"Updated contact: {updated_contact.email}")

# Update marketing consent
consent_update = ContactUpdate(
    marketing_consent=MarketingConsent(
        email=True,
        sms=True,
        whatsapp=False
    )
)

contact = client.contacts.update("contact_123456789", consent_update)

# Update specific fields only
partial_update = ContactUpdate(
    country="Canada"
)
contact = client.contacts.update("contact_123456789", partial_update)

Updating Contact Lifetime Value

Track revenue from customer purchases:

from decimal import Decimal
from konigle.models.comm import ContactUpdateLTV

# Record a purchase
ltv_data = ContactUpdateLTV(
    email="customer@example.com",
    value=Decimal("99.99"),
    currency="USD"
)

contact = client.contacts.update_ltv(ltv_data)
print(f"Updated LTV: {contact.ltv} {contact.ltv_currency}")
print(f"Last purchase: {contact.last_purchased_at}")

Currently there is not currency conversions. All the updates must be in the same currency.

Deleting Contacts

# Delete a contact
success = client.contacts.delete("contact_123456789")
if success:
    print("Contact deleted successfully")
else:
    print("Failed to delete contact")

Async Operations

import asyncio
import konigle
from konigle.models.comm import ContactCreate

async def manage_contacts():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create contact
        contact_data = ContactCreate(
            email="async@example.com",
            first_name="Async",
            last_name="User",
            source="migration",
            tags=["async"]
        )
        contact = await client.contacts.create(contact_data)

        # List contacts
        contacts = await client.contacts.list(page=1, page_size=10)

        # Update contact
        from konigle.models.comm import ContactUpdate
        update_data = ContactUpdate(tags=["async", "updated"])
        updated_contact = await client.contacts.update(
            contact.id,
            update_data
        )

        # Delete contact
        await client.contacts.delete(contact.id)

asyncio.run(manage_contacts())

CLI Commands

The Konigle CLI provides comprehensive contact management commands.

Contact Creation

# Create a basic contact
konigle comm contacts create \
    --email "customer@example.com" \
    --first-name "John" \
    --last-name "Doe" \
    --phone "+1234567890" \
    --country "United States" \
    --source "lead" \
    --tag "newsletter" \
    --tag "blog-subscriber"

# Create contact with consent preferences
konigle comm contacts create \
    --email "customer@example.com" \
    --first-name "Jane" \
    --source "purchase" \
    --email-consent \
    --no-sms-consent \
    --whatsapp-consent

Contact Listing

# List all contacts
konigle comm contacts list

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

# Search by email
konigle comm contacts list --search "example.com"

# Filter by source
konigle comm contacts list --source "purchase"

# Filter by tags
konigle comm contacts list --tags "newsletter,premium"

Contact Details

# Get specific contact details
konigle comm contacts get contact_123456789

Contact Updates

# Update contact name
konigle comm contacts update contact_123456789 \
    --first-name "Jonathan" \
    --last-name "Smith"

# Update contact tags
konigle comm contacts update contact_123456789 \
    --tag "newsletter" \
    --tag "premium" \
    --tag "vip"

# Update marketing consent
konigle comm contacts update contact_123456789 \
    --email-consent \
    --no-sms-consent

Contact LTV Update

# Record a purchase
konigle comm contacts update-ltv \
    --email "customer@example.com" \
    --value 99.99 \
    --currency "USD"

# Record another purchase (adds to existing LTV)
konigle comm contacts update-ltv \
    --email "customer@example.com" \
    --value 149.99 \
    --currency "USD"

Contact Deletion

# Delete contact with confirmation
konigle comm contacts delete contact_123456789

# Delete contact without confirmation
konigle comm contacts delete contact_123456789 --yes