> ## 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 contact lists, contacts, subscription topics, custom properties, and dynamic segments with the audience service in the Lettr PHP SDK.

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:

```php theme={null}
$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.

```php theme={null}
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);
```

<Card title="API Reference" icon="book" href="/api-reference/audience/list-audience-lists">
  GET /audience/lists
</Card>

## Contacts

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

```php theme={null}
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`.

<Card title="API Reference" icon="book" href="/api-reference/audience/list-audience-contacts">
  GET /audience/contacts
</Card>

### Double opt-in

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

```php theme={null}
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 operations

```php theme={null}
use Lettr\Dto\Audience\BulkCreateAudienceContactsData;
use Lettr\Dto\Audience\BulkAttachContactsToListsData;

// Create many contacts at once
$result = $lettr->audience()->contacts()->bulkCreate(new BulkCreateAudienceContactsData(
    emails: ['a@example.com', 'b@example.com', 'c@example.com'],
    listId: $list->id,                       // optional
    properties: ['source' => 'import'],      // optional, applied to all
));

// Attach / detach contacts to lists in bulk
$lettr->audience()->contacts()->bulkAttachLists(new BulkAttachContactsToListsData(/* ... */));
```

### Single relationships

```php theme={null}
// 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);
```

<Card title="API Reference" icon="book" href="/api-reference/audience/attach-contact-to-list">
  POST /audience/contacts/{contactId}/lists/{listId}
</Card>

## Topics

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

```php theme={null}
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
));
```

<Card title="API Reference" icon="book" href="/api-reference/audience/list-audience-topics">
  GET /audience/topics
</Card>

## Properties

Properties are typed custom fields stored on each contact.

```php theme={null}
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
));
```

<Card title="API Reference" icon="book" href="/api-reference/audience/list-audience-properties">
  GET /audience/properties
</Card>

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

```php theme={null}
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.

<Card title="API Reference" icon="book" href="/api-reference/audience/list-audience-segments">
  GET /audience/segments
</Card>

## What's Next

<CardGroup cols={2}>
  <Card title="Campaigns" icon="paper-plane" href="/quickstart/php/campaigns">
    Send to your audience
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/audience/list-audience-lists">
    Full audience API reference
  </Card>
</CardGroup>