Audience

The audience API manages everything campaigns send to: contact lists, the contacts themselves, subscription topics, custom properties, and dynamic segments. Everything is reached through Lettr::audience():

use Lettr\Laravel\Facades\Lettr;

Lettr::audience()->contacts();    // individual contacts
Lettr::audience()->lists();       // contact lists
Lettr::audience()->segments();    // dynamic segments
Lettr::audience()->topics();      // subscription topics
Lettr::audience()->properties();  // custom contact properties

All list() endpoints are paginated and return a response object exposing the data collection, a pagination object, and a hasMore() helper.

Contacts

A contact is an email address with optional custom properties, optionally attached to a list on creation.

use Lettr\Dto\Audience\CreateAudienceContactData;
use Lettr\Dto\Audience\UpdateAudienceContactData;
use Lettr\Dto\Audience\ListAudienceContactsFilter;
use Lettr\Enums\AudienceContactStatus;

// Create (optionally attach to a list and set custom properties)
$contact = Lettr::audience()->contacts()->create(new CreateAudienceContactData(
    email: 'jane@example.com',
    listId: 'list-uuid',
    properties: ['first_name' => 'Jane', 'plan' => 'pro'],
));

$contact->id;     // "contact-uuid"
$contact->email;  // "jane@example.com"
$contact->status; // AudienceContactStatus::Subscribed

// List with filtering and pagination
$response = Lettr::audience()->contacts()->list(
    ListAudienceContactsFilter::create()
        ->page(1)
        ->perPage(50)
        ->search('jane')
        ->status(AudienceContactStatus::Subscribed)
        ->listId('list-uuid')
);

foreach ($response->contacts as $contact) {
    // ...
}
$response->pagination->total;
$response->hasMore();

// Get, update, delete
$contact = Lettr::audience()->contacts()->get('contact-uuid');

Lettr::audience()->contacts()->update('contact-uuid', new UpdateAudienceContactData(
    status: AudienceContactStatus::Unsubscribed,
    properties: ['plan' => 'enterprise'],
));

Lettr::audience()->contacts()->delete('contact-uuid');

Contact status is one of Subscribed, Unsubscribed, Bounced, Complained, or Unverified.

API Reference

GET /audience/contacts

Double opt-in

Pass a DoubleOptInConfig to create the contact as unverified and trigger a confirmation email — the contact becomes subscribed once they click the link.

use Lettr\Dto\Audience\CreateAudienceContactData;
use Lettr\Dto\Audience\DoubleOptInConfig;

Lettr::audience()->contacts()->create(new CreateAudienceContactData(
    email: 'jane@example.com',
    doubleOptIn: new DoubleOptInConfig(
        from: 'hello@example.com',
        subject: 'Confirm your subscription',
        templateSlug: 'email-confirmation',
        redirectUrl: 'https://example.com/confirmed',
        fromName: 'Example',          // optional
    ),
));

Bulk create contacts

bulkCreate() takes up to 1000 contacts per request in one of two shapes. forEmails() builds the flat shape, where every address shares the batch-wide lists, properties and topics:

use Lettr\Dto\Audience\BulkCreateAudienceContactsData;

$result = Lettr::audience()->contacts()->bulkCreate(
    BulkCreateAudienceContactsData::forEmails(
        emails: ['a@example.com', 'b@example.com'],
        listIds: ['list-uuid'],
        properties: ['source' => 'spring-campaign'],
    )
);

forContacts() 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:

use Lettr\Dto\Audience\AudienceTopicSubscription;
use Lettr\Dto\Audience\BulkAudienceContactRow;
use Lettr\Dto\Audience\BulkCreateAudienceContactsData;

$result = Lettr::audience()->contacts()->bulkCreate(
    BulkCreateAudienceContactsData::forContacts(
        contacts: [
            new BulkAudienceContactRow(
                email: 'cara@example.com',
                properties: ['plan' => 'pro'],
                listIds: ['vip-list-uuid'],
                topics: [AudienceTopicSubscription::optIn('newsletter-uuid')],
            ),
            new BulkAudienceContactRow(
                email: 'dan@example.com',
                topics: [AudienceTopicSubscription::optOut('promos-uuid')],
            ),
        ],
        listIds: ['everyone-list-uuid'],
        properties: ['source' => 'spring-campaign'],
        updateExisting: false,
    )
);

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 errors while the rest of the batch commits — the API still returns 201. Always check hasErrors().

$result->created;        // int
$result->alreadyExisted; // int
$result->updated;        // int — existing contacts this request changed

if ($result->hasErrors()) {
    foreach ($result->errors as $error) {
        // index is zero-based into the rows you submitted
        Log::warning("Bulk import row {$error->index} ({$error->email}) skipped: {$error->error}");
    }
}

// Every contact that exists after the request, in submission order
$ids = $result->contactIds();
$caraId = $result->idFor('cara@example.com'); // case-insensitive lookup

$error->errorCode is a Lettr\Enums\BulkAudienceContactErrorCode (or a plain string for a code added server-side): missing_email, invalid_email, invalid_property_value, unknown_property_key, unknown_list, unknown_topic, or invalid_topic_subscription.

alreadyExisted 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.

Membership

$result->contactIds() from a bulkCreate() feeds straight into the bulk membership calls, so no id lookup is needed in between:

use Lettr\Dto\Audience\BulkAttachContactsToListsData;
use Lettr\Dto\Audience\BulkDetachContactsFromListsData;
use Lettr\Dto\Audience\BulkAudienceContactTopicsData;

// Attach / detach a single contact to a list (true if newly attached)
$attached = Lettr::audience()->contacts()->attachList('contact-uuid', 'list-uuid');
Lettr::audience()->contacts()->detachList('contact-uuid', 'list-uuid');

// Bulk attach / detach (up to 1000 contacts × 50 lists)
$attach = Lettr::audience()->contacts()->bulkAttachLists(new BulkAttachContactsToListsData(
    contactIds: ['contact-1', 'contact-2'],
    listIds: ['list-1', 'list-2'],
));
$attach->attached;        // int
$attach->alreadyAttached; // int
$attach->totalPairs;      // int

Lettr::audience()->contacts()->bulkDetachLists(new BulkDetachContactsFromListsData(
    contactIds: ['contact-1'],
    listIds: ['list-1'],
));

// Subscribe / unsubscribe a contact to a topic (true if newly subscribed)
Lettr::audience()->contacts()->subscribeTopic('contact-uuid', 'topic-uuid');
Lettr::audience()->contacts()->unsubscribeTopic('contact-uuid', 'topic-uuid');

// Bulk subscribe / unsubscribe (up to 1000 contacts × 50 topics)
$sub = Lettr::audience()->contacts()->bulkSubscribeTopics(new BulkAudienceContactTopicsData(
    contactIds: ['contact-1', 'contact-2'],
    topicIds: ['topic-1'],
));
$sub->subscribed;        // int
$sub->alreadySubscribed; // int
$sub->totalPairs;        // int

$unsub = Lettr::audience()->contacts()->bulkUnsubscribeTopics(new BulkAudienceContactTopicsData(
    contactIds: ['contact-1'],
    topicIds: ['topic-1'],
));
$unsub->unsubscribed; // int
$unsub->totalPairs;   // int

Every bulk membership call processes the full cartesian product of its ids. Unsubscribing ignores pairs that don’t exist, so unsubscribed can be lower than totalPairs.

API Reference

POST /audience/contacts/bulk

Lists

A list is a static collection of contacts.

use Lettr\Dto\Audience\CreateAudienceListData;
use Lettr\Dto\Audience\UpdateAudienceListData;
use Lettr\Dto\Audience\BulkDeleteAudienceListsData;
use Lettr\Dto\Audience\ListAudienceListsFilter;

$list = Lettr::audience()->lists()->create(new CreateAudienceListData(name: 'Newsletter'));
$list->id;
$list->name;
$list->contactsCount;

$response = Lettr::audience()->lists()->list(
    ListAudienceListsFilter::create()->page(1)->perPage(20)
);

$list = Lettr::audience()->lists()->get('list-uuid');

Lettr::audience()->lists()->update('list-uuid', new UpdateAudienceListData(name: 'Weekly digest'));

Lettr::audience()->lists()->delete('list-uuid');

// Bulk delete (up to 50)
$result = Lettr::audience()->lists()->bulkDelete(new BulkDeleteAudienceListsData(
    listIds: ['list-1', 'list-2'],
));
$result->deleted; // int

API Reference

GET /audience/lists

Segments

A segment is a dynamic group defined by conditions. Groups are joined by OR, and conditions within a group are joined by AND.

use Lettr\Dto\Audience\CreateAudienceSegmentData;
use Lettr\Dto\Audience\UpdateAudienceSegmentData;
use Lettr\Dto\Audience\ListAudienceSegmentsFilter;
use Lettr\Dto\Audience\SegmentConditionsInput;
use Lettr\Dto\Audience\SegmentConditionGroup;
use Lettr\Dto\Audience\SegmentCondition;
use Lettr\Enums\SegmentOperator;

$conditions = new SegmentConditionsInput(groups: [
    new SegmentConditionGroup(conditions: [
        new SegmentCondition('email', SegmentOperator::EndsWith, '@example.com'),
        new SegmentCondition('plan', SegmentOperator::Equals, 'pro'),
    ]),
]);

$segment = Lettr::audience()->segments()->create(new CreateAudienceSegmentData(
    name: 'Pro users at example.com',
    conditions: $conditions,
    listId: 'list-uuid', // optional: restrict to one list (null = all lists)
));

$response = Lettr::audience()->segments()->list(
    ListAudienceSegmentsFilter::create()->listId('list-uuid')
);

$segment = Lettr::audience()->segments()->get('segment-uuid');

// The update DTO uses a builder — only the touched fields are sent
Lettr::audience()->segments()->update('segment-uuid', UpdateAudienceSegmentData::empty()
    ->withName('Renamed segment')
    ->withConditions($conditions));

Lettr::audience()->segments()->delete('segment-uuid');

Operators that don’t take a value (SegmentOperator::IsTrue, SegmentOperator::IsFalse) report this via requiresValue().

API Reference

GET /audience/segments

Topics

Topics are subscription categories contacts can opt in or out of.

use Lettr\Dto\Audience\CreateAudienceTopicData;
use Lettr\Dto\Audience\UpdateAudienceTopicData;
use Lettr\Dto\Audience\ListAudienceTopicsFilter;
use Lettr\Enums\AudienceTopicDefaultSubscription;
use Lettr\Enums\AudienceTopicVisibility;

$topic = Lettr::audience()->topics()->create(new CreateAudienceTopicData(
    name: 'Product updates',
    description: 'Occasional product news',
    defaultSubscription: AudienceTopicDefaultSubscription::OptIn, // immutable after creation
    visibility: AudienceTopicVisibility::PublicVisibility,
));

$response = Lettr::audience()->topics()->list(
    ListAudienceTopicsFilter::create()->perPage(20)
);

$topic = Lettr::audience()->topics()->get('topic-uuid');

// default_subscription cannot be changed after creation
Lettr::audience()->topics()->update('topic-uuid', new UpdateAudienceTopicData(
    name: 'Product news',
    visibility: AudienceTopicVisibility::PrivateVisibility,
));

Lettr::audience()->topics()->delete('topic-uuid');

API Reference

GET /audience/topics

Properties

Custom contact properties have an immutable name (must match ^[a-z][a-z0-9_]*$) and an immutable type. Only the fallback value can be updated.

use Lettr\Dto\Audience\CreateAudiencePropertyData;
use Lettr\Dto\Audience\UpdateAudiencePropertyData;
use Lettr\Dto\Audience\ListAudiencePropertiesFilter;
use Lettr\Enums\AudiencePropertyType;

$property = Lettr::audience()->properties()->create(new CreateAudiencePropertyData(
    name: 'plan',
    type: AudiencePropertyType::StringType,  // StringType | NumberType | BooleanType | DateType | JsonType
    fallbackValue: 'free',
));

$response = Lettr::audience()->properties()->list(
    ListAudiencePropertiesFilter::create()->page(1)
);

$property = Lettr::audience()->properties()->get('property-uuid');

// Only the fallback can change — use the named constructors
Lettr::audience()->properties()->update('property-uuid', UpdateAudiencePropertyData::withFallback('basic'));
Lettr::audience()->properties()->update('property-uuid', UpdateAudiencePropertyData::clearFallback());

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

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

​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

Membership

Lists

Segments

Topics

Properties

What’s Next