> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audience

> Manage contacts, lists, subscription topics, custom properties, and dynamic segments with the Lettr Java SDK Audience service.

The `lettr.audience()` service manages everything campaigns send to. Each kind is a sub-service:

```java theme={null}
import com.lettr.Lettr;

Lettr lettr = new Lettr("your-api-key");

lettr.audience().contacts();    // individual contacts
lettr.audience().lists();       // contact lists
lettr.audience().topics();      // subscription topics
lettr.audience().properties();  // custom contact properties
lettr.audience().segments();    // dynamic segments
```

## Contacts

```java theme={null}
import com.lettr.services.audience.contacts.model.*;
import java.util.Map;

// Create (optionally attach to a list and set properties)
AudienceContactView contact = lettr.audience().contacts().create(
    CreateAudienceContactOptions.builder()
        .email("jane@example.com")
        .listId("list-uuid")
        .properties(Map.of("first_name", "Jane", "plan", "pro"))
        .build()
);
System.out.println(contact.getId() + " " + contact.getEmail() + " " + contact.getStatus());

// List with filters
ListAudienceContactsResponse page = lettr.audience().contacts().list(
    ListAudienceContactsParams.builder()
        .page(1)
        .perPage(50)
        .search("jane")
        .status(AudienceContactStatus.SUBSCRIBED)
        .listId("list-uuid")
        .build()
);

// Get, update, delete
lettr.audience().contacts().get("contact-uuid");
lettr.audience().contacts().update("contact-uuid",
    UpdateAudienceContactOptions.builder()
        .status(AudienceContactStatus.UNSUBSCRIBED)
        .properties(Map.of("plan", "enterprise"))
        .build()
);
lettr.audience().contacts().delete("contact-uuid");
```

Contact status values: `SUBSCRIBED`, `UNSUBSCRIBED`, `BOUNCED`, `COMPLAINED`, `UNVERIFIED`.

> [card] [API Reference](https://docs.lettr.com/api-reference/audience/list-audience-contacts.md)
>
> GET /audience/contacts

### Double opt-in

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

```java theme={null}
lettr.audience().contacts().create(
    CreateAudienceContactOptions.builder()
        .email("jane@example.com")
        .doubleOptIn(DoubleOptInConfig.builder()
            .from("hello@example.com")
            .subject("Confirm your subscription")
            .templateSlug("email-confirmation")
            .redirectUrl("https://example.com/confirmed")
            .build())
        .build()
);
```

### Bulk create contacts

`bulkCreate()` 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:

```java theme={null}
import java.util.List;
import java.util.Map;

lettr.audience().contacts().bulkCreate(
    BulkCreateAudienceContactsOptions.builder()
        .emails(List.of("a@example.com", "b@example.com"))
        .listIds(List.of("list-uuid"))
        .properties(Map.of("source", "spring-campaign"))
        .build()
);
```

The `contacts` shape addresses each contact individually. Row-level `listIds` 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:

```java theme={null}
BulkCreateAudienceContactsResponse result = lettr.audience().contacts().bulkCreate(
    BulkCreateAudienceContactsOptions.builder()
        .contacts(List.of(
            BulkAudienceContactRow.builder()
                .email("cara@example.com")
                .properties(Map.of("plan", "pro"))
                .listIds(List.of("vip-list-uuid"))
                .topic(AudienceTopicSubscription.optIn("newsletter-uuid"))
                .build(),
            BulkAudienceContactRow.builder()
                .email("dan@example.com")
                .topic(AudienceTopicSubscription.optOut("promos-uuid"))
                .build()
        ))
        .listIds(List.of("everyone-list-uuid"))
        .properties(Map.of("source", "spring-campaign"))
        .updateExisting(false)
        .build()
);
```

Set `emails` or `contacts`, not both. For a row with no extra data, `BulkAudienceContactRow.of("dan@example.com")` is shorthand for the builder.

> [!TIP]
>
> `AudienceTopicSubscription.optOut()` 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.

`updateExisting` 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 — and to let an opt-out drop an existing subscription.

#### Handling the result

> [!WARNING]
>
> A call that doesn't throw does **not** mean every row landed. Rows that fail validation are skipped and reported in `getErrors()` while the rest of the batch commits — the API still returns `201`. Always check `hasErrors()`.

```java theme={null}
System.out.println(result.getCreated() + " " + result.getAlreadyExisted() + " " + result.getUpdated());

if (result.hasErrors()) {
    for (BulkAudienceContactError e : result.getErrors()) {
        // getIndex() is zero-based into the rows you submitted
        System.out.println("row " + e.getIndex() + " (" + e.getEmail() + "): "
            + e.getErrorCode() + " — " + e.getError());
    }
}

// Every contact that exists after the request, in submission order
List<String> ids = result.getContactIds();
String caraId = result.findIdFor("cara@example.com"); // case-insensitive lookup
```

`getCode()` returns the same value as a `BulkAudienceContactErrorCode` enum: `missing_email`, `invalid_email`, `invalid_property_value`, `unknown_property_key`, `unknown_list`, `unknown_topic`, or `invalid_topic_subscription`.

> [!NOTE]
>
> `getAlreadyExisted()` and `getUpdated()` 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.getContactIds()` from a `bulkCreate()` feeds straight into the bulk membership calls, so no id lookup is needed in between:

```java theme={null}
// Single list / topic membership
lettr.audience().contacts().attachToList("contact-uuid", "list-uuid");
lettr.audience().contacts().detachFromList("contact-uuid", "list-uuid");
lettr.audience().contacts().subscribeToTopic("contact-uuid", "topic-uuid");
lettr.audience().contacts().unsubscribeFromTopic("contact-uuid", "topic-uuid");

// Bulk list membership (cartesian product of contactIds × listIds)
lettr.audience().contacts().bulkAttachToLists(
    BulkContactListsOptions.of(List.of("c1", "c2"), List.of("l1", "l2"))
);
lettr.audience().contacts().bulkDetachFromLists(
    BulkContactListsOptions.of(List.of("c1"), List.of("l1"))
);

// Bulk topic membership (cartesian product of contactIds × topicIds)
BulkSubscribeContactsResponse sub = lettr.audience().contacts().bulkSubscribeToTopics(
    BulkContactTopicsOptions.of(List.of("c1", "c2"), List.of("t1"))
);
System.out.println(sub.getSubscribed() + " " + sub.getAlreadySubscribed() + " " + sub.getTotalPairs());

BulkUnsubscribeContactsResponse unsub = lettr.audience().contacts().bulkUnsubscribeFromTopics(
    BulkContactTopicsOptions.of(List.of("c1"), List.of("t1"))
);
System.out.println(unsub.getUnsubscribed() + " " + unsub.getTotalPairs());
```

Both topic calls process every `contactIds × topicIds` combination, up to 1000 contacts × 50 topics. Unsubscribing ignores pairs that don't exist, so `getUnsubscribed()` can be lower than `getTotalPairs()`.

> [card] [API Reference](https://docs.lettr.com/api-reference/audience/bulk-create-contacts.md)
>
> POST /audience/contacts/bulk

## Lists

```java theme={null}
import com.lettr.services.audience.lists.model.*;

AudienceListView list = lettr.audience().lists().create(
    CreateAudienceListOptions.of("Newsletter")
);
System.out.println(list.getId() + " " + list.getName() + " " + list.getContactsCount());

lettr.audience().lists().get("list-uuid");
lettr.audience().lists().update("list-uuid",
    UpdateAudienceListOptions.builder().name("Weekly digest").build());
lettr.audience().lists().delete("list-uuid");

// Bulk delete
lettr.audience().lists().bulkDelete(
    BulkDeleteAudienceListsOptions.of(List.of("l1", "l2"))
);
```

> [card] [API Reference](https://docs.lettr.com/api-reference/audience/list-audience-lists.md)
>
> GET /audience/lists

## Segments

A segment is a dynamic group defined by conditions. Groups are joined by **OR**; conditions within a group by **AND**. Build them with `SegmentConditionsInput`, `SegmentConditionGroup`, `SegmentCondition`, and the `SegmentOperator` enum.

```java theme={null}
import com.lettr.services.audience.segments.model.*;

lettr.audience().segments().create(
    CreateAudienceSegmentOptions.builder()
        .name("Pro users at example.com")
        .listId("list-uuid")  // optional: restrict to one list
        .conditions(SegmentConditionsInput.of(
            SegmentConditionGroup.of(
                SegmentCondition.of("email", SegmentOperator.ENDS_WITH, "@example.com"),
                SegmentCondition.of("plan", SegmentOperator.EQUALS, "pro")
            )
        ))
        .build()
);

lettr.audience().segments().get("segment-uuid");
lettr.audience().segments().delete("segment-uuid");
```

> [card] [API Reference](https://docs.lettr.com/api-reference/audience/list-audience-segments.md)
>
> GET /audience/segments

## Topics

```java theme={null}
import com.lettr.services.audience.topics.model.*;

lettr.audience().topics().create(
    CreateAudienceTopicOptions.builder()
        .name("Product updates")
        .description("Occasional product news")
        .defaultSubscription(AudienceTopicDefaultSubscription.OPT_IN)  // immutable after creation
        .visibility(AudienceTopicVisibility.PUBLIC)
        .build()
);

lettr.audience().topics().get("topic-uuid");
lettr.audience().topics().delete("topic-uuid");
```

> [card] [API Reference](https://docs.lettr.com/api-reference/audience/list-audience-topics.md)
>
> GET /audience/topics

## Properties

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

```java theme={null}
import com.lettr.services.audience.properties.model.*;

lettr.audience().properties().create(
    CreateAudiencePropertyOptions.builder()
        .name("plan")
        .type(AudiencePropertyType.STRING)  // STRING | NUMBER | BOOLEAN | DATE | JSON
        .fallbackValue("free")
        .build()
);

lettr.audience().properties().get("property-uuid");
lettr.audience().properties().delete("property-uuid");
```

> [card] [API Reference](https://docs.lettr.com/api-reference/audience/list-audience-properties.md)
>
> GET /audience/properties

## What's Next

> [card] [Campaigns](https://docs.lettr.com/quickstart/java/campaigns.md)
>
> Send to your audience

> [card] [API Reference](https://docs.lettr.com/api-reference/audience/list-audience-lists.md)
>
> Full audience API reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.