Audience

The client.Audience service manages everything campaigns send to. Each kind is a sub-service:

import lettr "github.com/lettr-com/lettr-go"

client := lettr.NewClient("your-api-key")

client.Audience.Contacts    // individual contacts
client.Audience.Lists       // contact lists
client.Audience.Topics      // subscription topics
client.Audience.Properties  // custom contact properties
client.Audience.Segments    // dynamic segments

Like the other services, every method takes a context.Context as its first argument.

Contacts

// Create (optionally attach to a list and set properties)
listID := "list-uuid"
contact, err := client.Audience.Contacts.Create(ctx, &lettr.CreateAudienceContactRequest{
    Email:      "jane@example.com",
    ListID:     &listID,
    Properties: map[string]string{"first_name": "Jane", "plan": "pro"},
})
fmt.Println(contact.Data.ID, contact.Data.Email, contact.Data.Status)

// List with filters
page, err := client.Audience.Contacts.List(ctx, &lettr.ListAudienceContactsParams{
    Page:    1,
    PerPage: 50,
    Search:  "jane",
    Status:  lettr.ContactStatusSubscribed,
    ListID:  "list-uuid",
})

// Get, update, delete
_, err = client.Audience.Contacts.Get(ctx, "contact-uuid")
_, err = client.Audience.Contacts.Update(ctx, "contact-uuid", &lettr.UpdateAudienceContactRequest{
    Status: lettr.ContactStatusUnsubscribed,
})
err = client.Audience.Contacts.Delete(ctx, "contact-uuid")

Contact status constants: ContactStatusSubscribed, ContactStatusUnsubscribed, ContactStatusBounced, ContactStatusComplained, ContactStatusUnverified.

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:

_, err = client.Audience.Contacts.Create(ctx, &lettr.CreateAudienceContactRequest{
    Email: "jane@example.com",
    DoubleOptIn: &lettr.DoubleOptInConfig{
        From:         "hello@example.com",
        Subject:      "Confirm your subscription",
        TemplateSlug: "email-confirmation",
        RedirectURL:  "https://example.com/confirmed",
    },
})

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:

_, err = client.Audience.Contacts.BulkCreate(ctx, &lettr.BulkCreateAudienceContactsRequest{
    Emails:     []string{"a@example.com", "b@example.com"},
    ListIDs:    []string{"list-uuid"},
    Properties: map[string]string{"source": "spring-campaign"},
})

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:

resp, err := client.Audience.Contacts.BulkCreate(ctx, &lettr.BulkCreateAudienceContactsRequest{
    Contacts: []lettr.BulkAudienceContactRow{
        {
            Email:      "cara@example.com",
            Properties: map[string]string{"plan": "pro"},
            ListIDs:    []string{"vip-list-uuid"},
            Topics:     []lettr.AudienceTopicSubscription{lettr.SubscribeTopic("newsletter-uuid")},
        },
        {
            Email:  "dan@example.com",
            Topics: []lettr.AudienceTopicSubscription{lettr.UnsubscribeTopic("promos-uuid")},
        },
    },
    ListIDs:        []string{"everyone-list-uuid"},
    Properties:     map[string]string{"source": "spring-campaign"},
    UpdateExisting: false,
})

Fill in Emails or Contacts, not both.

lettr.UnsubscribeTopic 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 nil error 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().

data := resp.Data
fmt.Println(data.Created, data.AlreadyExisted, data.Updated)

if data.HasErrors() {
    for _, e := range data.Errors {
        // Index is zero-based into the rows you submitted
        fmt.Printf("row %d (%s): %s — %s\n", e.Index, e.Email, e.ErrorCode, e.Error)
    }
}

// Every contact that exists after the request, in submission order
ids := data.ContactIDs()
caraID, ok := data.IDFor("cara@example.com") // case-insensitive lookup

ErrorCode is one of the lettr.BulkContactError* constants: 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

data.ContactIDs() from a BulkCreate feeds straight into the bulk membership calls, so no id lookup is needed in between:

// Single list / topic membership
_, err = client.Audience.Contacts.AttachToList(ctx, "contact-uuid", "list-uuid")
err = client.Audience.Contacts.DetachFromList(ctx, "contact-uuid", "list-uuid")
_, err = client.Audience.Contacts.SubscribeToTopic(ctx, "contact-uuid", "topic-uuid")
err = client.Audience.Contacts.UnsubscribeFromTopic(ctx, "contact-uuid", "topic-uuid")

// Bulk list membership (cartesian product of ContactIDs × ListIDs)
_, err = client.Audience.Contacts.BulkAttachToLists(ctx, &lettr.BulkContactsListsRequest{
    ContactIDs: []string{"c1", "c2"},
    ListIDs:    []string{"l1", "l2"},
})
_, err = client.Audience.Contacts.BulkDetachFromLists(ctx, &lettr.BulkContactsListsRequest{
    ContactIDs: []string{"c1"},
    ListIDs:    []string{"l1"},
})

// Bulk topic membership (cartesian product of ContactIDs × TopicIDs)
sub, err := client.Audience.Contacts.BulkSubscribeToTopics(ctx, &lettr.BulkContactsTopicsRequest{
    ContactIDs: []string{"c1", "c2"},
    TopicIDs:   []string{"t1"},
})
fmt.Println(sub.Data.Subscribed, sub.Data.AlreadySubscribed, sub.Data.TotalPairs)

unsub, err := client.Audience.Contacts.BulkUnsubscribeFromTopics(ctx, &lettr.BulkContactsTopicsRequest{
    ContactIDs: []string{"c1"},
    TopicIDs:   []string{"t1"},
})
fmt.Println(unsub.Data.Unsubscribed, unsub.Data.TotalPairs)

Both topic calls process every ContactIDs × TopicIDs combination, up to 1000 contacts × 50 topics. Unsubscribing ignores pairs that don’t exist, so Unsubscribed can be lower than TotalPairs.

API Reference

POST /audience/contacts/bulk

Lists

list, err := client.Audience.Lists.Create(ctx, &lettr.CreateAudienceListRequest{Name: "Newsletter"})
fmt.Println(list.Data.ID, list.Data.Name, list.Data.ContactsCount)

_, err = client.Audience.Lists.Get(ctx, "list-uuid")
_, err = client.Audience.Lists.Update(ctx, "list-uuid", &lettr.UpdateAudienceListRequest{Name: "Weekly digest"})
err = client.Audience.Lists.Delete(ctx, "list-uuid")

// Bulk delete (takes a slice of IDs directly)
_, err = client.Audience.Lists.BulkDelete(ctx, []string{"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.

value := "@example.com"
plan := "pro"
_, err = client.Audience.Segments.Create(ctx, &lettr.CreateAudienceSegmentRequest{
    Name: "Pro users at example.com",
    Conditions: lettr.SegmentConditionsInput{
        Groups: []lettr.SegmentConditionGroup{
            {
                Conditions: []lettr.SegmentCondition{
                    {Field: "email", Operator: lettr.SegmentOperatorEndsWith, Value: &value},
                    {Field: "plan", Operator: lettr.SegmentOperatorEquals, Value: &plan},
                },
            },
        },
    },
})

_, err = client.Audience.Segments.Get(ctx, "segment-uuid")
err = client.Audience.Segments.Delete(ctx, "segment-uuid")

Operator constants include SegmentOperatorEquals, SegmentOperatorContains, SegmentOperatorEndsWith, SegmentOperatorIsTrue, and others.

API Reference

GET /audience/segments

Topics

_, err = client.Audience.Topics.Create(ctx, &lettr.CreateAudienceTopicRequest{
    Name:                "Product updates",
    DefaultSubscription: lettr.TopicDefaultSubscriptionOptIn,  // immutable after creation
    Visibility:          lettr.TopicVisibilityPublic,
})

_, err = client.Audience.Topics.Get(ctx, "topic-uuid")
err = client.Audience.Topics.Delete(ctx, "topic-uuid")

API Reference

GET /audience/topics

Properties

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

_, err = client.Audience.Properties.Create(ctx, &lettr.CreateAudiencePropertyRequest{
    Name: "plan",
    Type: lettr.PropertyTypeString,  // String, Number, Boolean, Date, JSON
})

_, err = client.Audience.Properties.Get(ctx, "property-uuid")
err = client.Audience.Properties.Delete(ctx, "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