Audience

The client.audience resource manages everything campaigns send to. Each kind is a sub-resource:

import lettr

client = lettr.Lettr("lttr_your_api_key")

client.audience.contacts    # individual contacts
client.audience.lists       # contact lists
client.audience.topics      # subscription topics
client.audience.properties  # custom contact properties
client.audience.segments    # dynamic segments

Contacts

# Create (optionally attach to a list and set properties)
contact = client.audience.contacts.create(
    email="jane@example.com",
    list_id="list-uuid",
    properties={"first_name": "Jane", "plan": "pro"},
)
print(contact.id, contact.email, contact.status)

# List with filters
page = client.audience.contacts.list(
    page=1,
    per_page=50,
    search="jane",
    status="subscribed",
    list_id="list-uuid",
)
for c in page.contacts:
    print(c.email, c.status)

# Get, update, delete
client.audience.contacts.get("contact-uuid")
client.audience.contacts.update(
    "contact-uuid",
    status="unsubscribed",
    properties={"plan": "enterprise"},
)
client.audience.contacts.delete("contact-uuid")

Contact status is "subscribed", "unsubscribed", "bounced", "complained", or "unverified".

API Reference

GET /audience/contacts

Double opt-in

Pass a double_opt_in config to create the contact as unverified and send a confirmation email — they become subscribed after clicking the link:

client.audience.contacts.create(
    email="jane@example.com",
    double_opt_in={
        "from": "hello@example.com",
        "subject": "Confirm your subscription",
        "template_slug": "email-confirmation",
        "redirect_url": "https://example.com/confirmed",
    },
)

Bulk create contacts

bulk_create() takes up to 1000 contacts per request in one of two shapes. The flat emails shape gives every address the same lists, properties and topics:

client.audience.contacts.bulk_create(
    emails=["a@example.com", "b@example.com"],
    list_ids=["list-uuid"],
    properties={"source": "spring-campaign"},
)

The contacts shape addresses each contact individually. Row-level list_ids and topics are applied on top of the batch-wide ones, and a row’s properties key overrides the batch-wide value for that key:

from lettr import BulkContactRow, TopicSubscription

result = client.audience.contacts.bulk_create(
    contacts=[
        BulkContactRow(
            email="cara@example.com",
            properties={"plan": "pro"},
            list_ids=["vip-list-uuid"],
            topics=[TopicSubscription.opt_in("newsletter-uuid")],
        ),
        BulkContactRow(
            email="dan@example.com",
            topics=[TopicSubscription.opt_out("promos-uuid")],
        ),
    ],
    list_ids=["everyone-list-uuid"],
    properties={"source": "spring-campaign"},
    update_existing=False,
)

Pass emails or contacts — omitting both raises ValueError.

TopicSubscription.opt_out() suppresses a topic for that contact in the same request. Useful when a topic’s default_subscription is opt_out, which auto-subscribes newly created contacts — a row-level opt-out cancels that instead of needing a second call. A row-level opt-out also beats a batch-level opt-in.

update_existing defaults to False, which leaves existing contacts’ properties alone (they are still attached to the requested lists). Set it to True to merge properties — submitted keys overwrite, absent keys are preserved. It governs properties only: a row-level opt-out drops an existing subscription either way.

Handling the result

A call that doesn’t raise does not mean every row landed. Rows that fail validation are skipped and reported in errors while the rest of the batch commits — the API still returns 201. Always check result.has_errors.

print(result.created, result.already_existed, result.updated)

if result.has_errors:
    for err in result.errors:
        # index is zero-based into the rows you submitted
        print(f"row {err.index} ({err.email}): {err.error_code} — {err.error}")

# Every contact that exists after the request, in submission order
ids = result.contact_ids
cara_id = result.id_for("cara@example.com")  # case-insensitive lookup

error_code is one of missing_email, invalid_email, invalid_property_value, unknown_property_key, unknown_list, unknown_topic, or invalid_topic_subscription.

already_existed and updated overlap by design — “was the address already in the audience?” versus “did this request change the contact?” — so they don’t sum to the row count. A contact that already existed and got attached to a list is counted in both.

Bulk membership

result.contact_ids from a bulk_create() feeds straight into the bulk membership calls, so no id lookup is needed in between:

# Single list / topic membership
client.audience.contacts.add_to_list(contact_id="contact-uuid", list_id="list-uuid")
client.audience.contacts.remove_from_list(contact_id="contact-uuid", list_id="list-uuid")
client.audience.contacts.subscribe_to_topic(contact_id="contact-uuid", topic_id="topic-uuid")
client.audience.contacts.unsubscribe_from_topic(contact_id="contact-uuid", topic_id="topic-uuid")

# Bulk list membership
client.audience.contacts.bulk_attach_lists(
    contact_ids=["c1", "c2"],
    list_ids=["l1", "l2"],
)
client.audience.contacts.bulk_detach_lists(contact_ids=["c1"], list_ids=["l1"])

# Bulk topic membership
sub = client.audience.contacts.bulk_subscribe_topics(
    contact_ids=["c1", "c2"],
    topic_ids=["t1"],
)
print(sub.subscribed, sub.already_subscribed, sub.total_pairs)

unsub = client.audience.contacts.bulk_unsubscribe_topics(
    contact_ids=["c1"],
    topic_ids=["t1"],
)
print(unsub.unsubscribed, unsub.total_pairs)

Both topic calls process every contact_ids × topic_ids combination, up to 1000 contacts × 50 topics. Unsubscribing ignores pairs that don’t exist, so unsubscribed can be lower than total_pairs.

bulk_unsubscribe_topics() and bulk_detach_lists() issue a DELETE with a request body. httpx handles that, but a proxy in front of your app may not.

API Reference

POST /audience/contacts/bulk

Lists

audience_list = client.audience.lists.create(name="Newsletter")
print(audience_list.id, audience_list.name, audience_list.contacts_count)

client.audience.lists.list(page=1, per_page=20)
client.audience.lists.get("list-uuid")
client.audience.lists.update("list-uuid", name="Weekly digest")
client.audience.lists.delete("list-uuid")

# Bulk delete
client.audience.lists.bulk_delete(list_ids=["l1", "l2"])

API Reference

GET /audience/lists

Segments

A segment is a dynamic group defined by conditions. Groups are joined by OR; conditions within a group by AND. Conditions are a plain dict matching the API schema:

client.audience.segments.create(
    name="Pro users at example.com",
    list_id="list-uuid",  # optional: restrict to one list
    conditions={
        "groups": [
            {
                "conditions": [
                    {"field": "email", "operator": "ends_with", "value": "@example.com"},
                    {"field": "plan", "operator": "equals", "value": "pro"},
                ],
            },
        ],
    },
)

client.audience.segments.list(list_id="list-uuid")
client.audience.segments.get("segment-uuid")
client.audience.segments.delete("segment-uuid")

Operators include equals, not_equals, contains, starts_with, ends_with, is_true, is_false, and others.

API Reference

GET /audience/segments

Topics

client.audience.topics.create(
    name="Product updates",
    description="Occasional product news",
    default_subscription="opt_in",  # "opt_in" | "opt_out" — immutable after creation
    visibility="public",            # "public" | "private"
)

client.audience.topics.list(per_page=20)
client.audience.topics.get("topic-uuid")
client.audience.topics.update("topic-uuid", name="Product news", visibility="private")
client.audience.topics.delete("topic-uuid")

API Reference

GET /audience/topics

Properties

Custom contact properties have an immutable name and type; only the fallback can be updated.

client.audience.properties.create(
    name="plan",
    type="string",          # "string" | "number" | "boolean" | "date" | "json"
    fallback_value="free",
)

client.audience.properties.list(page=1)
client.audience.properties.get("property-uuid")
client.audience.properties.delete("property-uuid")

API Reference

GET /audience/properties

What’s Next

Campaigns

Send to your audience

API Reference

Full audience API reference

Documentation

Quickstart

Learn

Integrations

Resources

Contacts

API Reference

Double opt-in

Bulk create contacts

Handling the result

Bulk membership

API Reference

Lists

API Reference

Segments

API Reference

Topics

API Reference

Properties

API Reference

What’s Next

Campaigns

API Reference

​Contacts

API Reference

​Double opt-in

​Bulk create contacts

​Handling the result

​Bulk membership

API Reference

​Lists

API Reference

​Segments

API Reference

​Topics

API Reference

​Properties

API Reference

​What’s Next

Campaigns

API Reference

Contacts

Double opt-in

Bulk create contacts

Handling the result

Bulk membership

Lists

Segments

Topics

Properties

What’s Next