Audience

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

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

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.

API Reference

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:

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:

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:

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.

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

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().

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.

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:

// 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().

API Reference

POST /audience/contacts/bulk

Lists

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"))
);

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. Build them with SegmentConditionsInput, SegmentConditionGroup, SegmentCondition, and the SegmentOperator enum.

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");

API Reference

GET /audience/segments

Topics

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");

API Reference

GET /audience/topics

Properties

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

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");

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