Audience

The $lettr->audience() service manages everything campaigns send to: contact lists, the contacts themselves, subscription topics, custom properties, and dynamic segments. Each is a sub-service:

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

All five expose the same CRUD shape — list(), get(), create(), update(), delete() — with a few bulk and relationship helpers on contacts and lists.

Lists

A list is a static collection of contacts.

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

// Create
$list = $lettr->audience()->lists()->create(new CreateAudienceListData(
    name: 'Newsletter subscribers',
));
echo $list->id;

// List, get, update, delete
$response = $lettr->audience()->lists()->list();
$list = $lettr->audience()->lists()->get($list->id);
$lettr->audience()->lists()->update($list->id, new UpdateAudienceListData(name: 'Renamed'));
$lettr->audience()->lists()->delete($list->id);

API Reference

GET /audience/lists

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
$contact = $lettr->audience()->contacts()->create(new CreateAudienceContactData(
    email: 'jane@example.com',
    listId: $list->id,                              // optional
    properties: ['first_name' => 'Jane', 'plan' => 'pro'], // optional
));

// List with filters
$response = $lettr->audience()->contacts()->list(
    ListAudienceContactsFilter::create()
        ->status(AudienceContactStatus::Subscribed)
        ->listId($list->id)
        ->search('example.com')
        ->perPage(50),
);

// Get, update, delete
$contact = $lettr->audience()->contacts()->get($contact->id);
$lettr->audience()->contacts()->update($contact->id, new UpdateAudienceContactData(
    status: AudienceContactStatus::Unsubscribed,
    properties: ['plan' => 'enterprise'],
));
$lettr->audience()->contacts()->delete($contact->id);

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

API Reference

GET /audience/contacts

Double opt-in

Pass a DoubleOptInConfig to send a confirmation email before the contact becomes subscribed:

use Lettr\Dto\Audience\DoubleOptInConfig;

$contact = $lettr->audience()->contacts()->create(new CreateAudienceContactData(
    email: 'jane@example.com',
    doubleOptIn: new DoubleOptInConfig(
        from: 'hello@yourdomain.com',
        subject: 'Confirm your subscription',
        templateSlug: 'double-opt-in',
        redirectUrl: 'https://example.com/confirmed',
        fromName: 'Your App',          // 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', 'c@example.com'],
        listIds: [$list->id],
        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().

use Lettr\Enums\BulkAudienceContactErrorCode;

echo $result->created, $result->alreadyExisted, $result->updated;

if ($result->hasErrors()) {
    foreach ($result->errors as $error) {
        // index is zero-based into the rows you submitted
        $code = $error->errorCode instanceof BulkAudienceContactErrorCode
            ? $error->errorCode->value
            : $error->errorCode;

        echo "row {$error->index} ({$error->email}): {$code} — {$error->error}";
    }
}

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

errorCode is a BulkAudienceContactErrorCode enum (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.

Bulk membership

$result->contactIds() from a bulkCreate() feeds straight into the bulk membership calls, so no id lookup is needed in between. Each processes every combination of contacts × lists (or topics), up to 1000 × 50:

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

// Lists
$lettr->audience()->contacts()->bulkAttachLists(new BulkAttachContactsToListsData(
    contactIds: ['c1', 'c2'],
    listIds: ['l1', 'l2'],
));
$lettr->audience()->contacts()->bulkDetachLists(new BulkDetachContactsFromListsData(
    contactIds: ['c1'],
    listIds: ['l1'],
));

// Topics
$sub = $lettr->audience()->contacts()->bulkSubscribeTopics(new BulkAudienceContactTopicsData(
    contactIds: ['c1', 'c2'],
    topicIds: ['t1'],
));
echo $sub->subscribed, $sub->alreadySubscribed, $sub->totalPairs;

$unsub = $lettr->audience()->contacts()->bulkUnsubscribeTopics(new BulkAudienceContactTopicsData(
    contactIds: ['c1'],
    topicIds: ['t1'],
));
echo $unsub->unsubscribed, $unsub->totalPairs;

Unsubscribing ignores pairs that don’t exist, so unsubscribed can be lower than totalPairs.

API Reference

POST /audience/contacts/bulk

Single relationships

// Lists
$lettr->audience()->contacts()->attachList($contactId, $listId);
$lettr->audience()->contacts()->detachList($contactId, $listId);

// Topics
$lettr->audience()->contacts()->subscribeTopic($contactId, $topicId);
$lettr->audience()->contacts()->unsubscribeTopic($contactId, $topicId);

API Reference

POST /audience/contacts//lists/

Topics

Topics are subscription categories contacts can opt in or out of (e.g. “Product updates”, “Promotions”).

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

$topic = $lettr->audience()->topics()->create(new CreateAudienceTopicData(
    name: 'Product updates',
    description: 'New features and changelog',                       // optional
    defaultSubscription: AudienceTopicDefaultSubscription::OptIn,    // optional: OptIn | OptOut
    visibility: AudienceTopicVisibility::PublicVisibility,          // optional: PublicVisibility | PrivateVisibility
));

API Reference

GET /audience/topics

Properties

Properties are typed custom fields stored on each contact.

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

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

API Reference

GET /audience/properties

Segments

A segment is a dynamic group defined by conditions over contact fields and properties. Conditions are grouped — conditions within a group are AND-ed, and groups are OR-ed together.

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

$segment = $lettr->audience()->segments()->create(new CreateAudienceSegmentData(
    name: 'Pro users on example.com',
    conditions: new SegmentConditionsInput([
        new SegmentConditionGroup([
            new SegmentCondition('plan', SegmentOperator::Equals, 'pro'),
            new SegmentCondition('email', SegmentOperator::EndsWith, '@example.com'),
        ]),
    ]),
    listId: $list->id, // optional — scope the segment to one list
));

Operators include Equals, NotEquals, Contains, StartsWith, EndsWith, GreaterThan, LessThan, Before, After, IsTrue, IsFalse, and their negations.

API Reference

GET /audience/segments

What’s Next

Campaigns

Send to your audience

API Reference

Full audience API reference

Documentation

Quickstart

Learn

Integrations

Resources

Lists

API Reference

Contacts

API Reference

Double opt-in

Bulk create contacts

Handling the result

Bulk membership

API Reference

Single relationships

API Reference

Topics

API Reference

Properties

API Reference

Segments

API Reference

What’s Next

Campaigns

API Reference

​Lists

API Reference

​Contacts

API Reference

​Double opt-in

​Bulk create contacts

​Handling the result

​Bulk membership

API Reference

​Single relationships

API Reference

​Topics

API Reference

​Properties

API Reference

​Segments

API Reference

​What’s Next

Campaigns

API Reference

Lists

Contacts

Double opt-in

Bulk create contacts

Handling the result

Bulk membership

Single relationships

Topics

Properties

Segments

What’s Next