Skip to main content
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 operations

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

// 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