Segments

Segments allow you to organize contacts into groups for targeted email campaigns. This guide covers creating, managing, and using segments with the Resend Go SDK.

Overview

Segments (formerly called “audiences”) provide a way to organize your global contacts into logical groups for broadcast campaigns. Unlike the legacy audience system, segments work with global contacts and support more flexible organization.

Terminology Update: Resend has renamed “audiences” to “segments”. The API still accepts audience_id for backward compatibility, but new integrations should use segment_id.

Creating a Segment

Create a new segment to organize your contacts.

import (
    "github.com/resend/resend-go/v3"
)

client := resend.NewClient("re_123456789")

params := &resend.CreateSegmentRequest{
    Name: "Premium Users",
}

segment, err := client.Segments.Create(params)
if err != nil {
    panic(err)
}

fmt.Printf("Created segment: %s (ID: %s)\n", segment.Name, segment.Id)

Name

string

required

The name of the segment. This will be visible in your Resend dashboard.

Retrieving a Segment

Get details about a specific segment.

Get Segment

segment, err := client.Segments.Get("seg-123456")
if err != nil {
    panic(err)
}

fmt.Println("Segment Name:", segment.Name)
fmt.Println("Created At:", segment.CreatedAt)
fmt.Println("ID:", segment.Id)

Listing Segments

Retrieve all segments in your account with optional pagination.

segments, err := client.Segments.List()
if err != nil {
    panic(err)
}

fmt.Printf("You have %d segment(s)\n", len(segments.Data))

for _, segment := range segments.Data {
    fmt.Printf("- %s (ID: %s)\n", segment.Name, segment.Id)
}

Deleting a Segment

Remove a segment from your account.

Remove Segment

removed, err := client.Segments.Remove("seg-123456")
if err != nil {
    panic(err)
}

fmt.Printf("Segment %s deleted: %v\n", removed.Id, removed.Deleted)

Deleting a segment does not delete the contacts within it. Contacts remain in your account as global contacts.

Managing Contacts in Segments

Segments are populated and managed through the Contacts API’s nested Segments service.

Adding Contacts to Segments

Add a contact to a segment using the Contacts.Segments.Add method.

Add Contact to Segment

// First, create a global contact
contactParams := &resend.CreateContactRequest{
    Email:     "[email protected]",
    FirstName: "John",
    LastName:  "Doe",
}

contact, err := client.Contacts.Create(contactParams)
if err != nil {
    panic(err)
}

// Then add the contact to a segment
addParams := &resend.AddContactSegmentRequest{
    ContactId: contact.Id,
    SegmentId: "seg-123456",
}

_, err = client.Contacts.Segments.Add(addParams)
if err != nil {
    panic(err)
}

fmt.Println("Contact added to segment")

Listing Contact’s Segments

Retrieve all segments a contact belongs to.

List Contact Segments

listParams := &resend.ListContactSegmentsRequest{
    ContactId: "contact-123",
}

segments, err := client.Contacts.Segments.List(listParams)
if err != nil {
    panic(err)
}

fmt.Printf("Contact is in %d segment(s):\n", len(segments.Data))
for _, seg := range segments.Data {
    fmt.Printf("  - %s (ID: %s)\n", seg.Name, seg.Id)
}

Removing Contacts from Segments

Remove a contact from a specific segment.

Remove Contact from Segment

removeParams := &resend.RemoveContactSegmentRequest{
    ContactId: "contact-123",
    SegmentId: "seg-123456",
}

removed, err := client.Contacts.Segments.Remove(removeParams)
if err != nil {
    panic(err)
}

fmt.Printf("Removed from segment: %v\n", removed.Deleted)

Relationship to Contacts

Segments work exclusively with global contacts (contacts created without an audience_id). Here’s the recommended workflow:

Create Global Contacts

Create contacts without specifying an audience_id:

contact, err := client.Contacts.Create(&resend.CreateContactRequest{
    Email:     "[email protected]",
    FirstName: "John",
    LastName:  "Doe",
})

Create Segments

Create segments to organize contacts:

segment, err := client.Segments.Create(&resend.CreateSegmentRequest{
    Name: "Premium Users",
})

Add Contacts to Segments

Associate contacts with segments:

_, err := client.Contacts.Segments.Add(&resend.AddContactSegmentRequest{
    ContactId: contact.Id,
    SegmentId: segment.Id,
})

Send Broadcasts

Send email campaigns to entire segments:

broadcast, err := client.Broadcasts.Create(&resend.CreateBroadcastRequest{
    SegmentId: segment.Id,
    From:      "[email protected]",
    Subject:   "Product Update",
    Html:      "<h1>Hello!</h1>",
})

Complete Example

Here’s a complete workflow demonstrating segment management:

Complete Segment Workflow

package main

import (
    "context"
    "fmt"
    "os"
    
    "github.com/resend/resend-go/v3"
)

func main() {
    ctx := context.Background()
    apiKey := os.Getenv("RESEND_API_KEY")
    client := resend.NewClient(apiKey)

    // 1. Create a segment
    segmentParams := &resend.CreateSegmentRequest{
        Name: "Premium Users",
    }

    segment, err := client.Segments.CreateWithContext(ctx, segmentParams)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created segment: %s (ID: %s)\n", segment.Name, segment.Id)

    // 2. Create a global contact
    contactParams := &resend.CreateContactRequest{
        Email:     "[email protected]",
        FirstName: "Premium",
        LastName:  "User",
    }

    contact, err := client.Contacts.CreateWithContext(ctx, contactParams)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created contact: %s\n", contact.Id)

    // 3. Add the contact to the segment
    addToSegment := &resend.AddContactSegmentRequest{
        ContactId: contact.Id,
        SegmentId: segment.Id,
    }

    _, err = client.Contacts.Segments.AddWithContext(ctx, addToSegment)
    if err != nil {
        panic(err)
    }
    fmt.Println("Added contact to segment")

    // 4. List all segments for this contact
    contactSegments, err := client.Contacts.Segments.ListWithContext(ctx, &resend.ListContactSegmentsRequest{
        ContactId: contact.Id,
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("\nContact is in %d segment(s):\n", len(contactSegments.Data))
    for _, seg := range contactSegments.Data {
        fmt.Printf("  - %s (ID: %s)\n", seg.Name, seg.Id)
    }

    // 5. Get segment details
    retrievedSegment, err := client.Segments.GetWithContext(ctx, segment.Id)
    if err != nil {
        panic(err)
    }
    fmt.Printf("\nRetrieved segment: %s\n", retrievedSegment.Name)

    // 6. List all segments
    segments, err := client.Segments.ListWithContext(ctx)
    if err != nil {
        panic(err)
    }
    fmt.Printf("You have %d segments in your project\n", len(segments.Data))

    // 7. Clean up: Remove the contact from the segment
    removeFromSegment, err := client.Contacts.Segments.RemoveWithContext(ctx, &resend.RemoveContactSegmentRequest{
        ContactId: contact.Id,
        SegmentId: segment.Id,
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("\nRemoved contact from segment: %v\n", removeFromSegment.Deleted)

    // 8. Clean up: Remove the contact
    removedContact, err := client.Contacts.RemoveWithContext(ctx, &resend.RemoveContactOptions{
        Id: contact.Id,
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Deleted contact: %v\n", removedContact.Deleted)

    // 9. Clean up: Remove the segment
    removedSegment, err := client.Segments.RemoveWithContext(ctx, segment.Id)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Deleted segment: %v\n", removedSegment.Deleted)
}

Using Segments with Broadcasts

Segments are primarily used to send broadcast email campaigns to groups of contacts.

Send Broadcast to Segment

// Create a broadcast for a segment
broadcastParams := &resend.CreateBroadcastRequest{
    SegmentId: "seg-123456",
    From:      "[email protected]",
    Subject:   "Monthly Newsletter",
    Html:      "<h1>This month's updates</h1><p>Content here...</p>",
    Name:      "Monthly Newsletter - January",
}

broadcast, err := client.Broadcasts.Create(broadcastParams)
if err != nil {
    panic(err)
}

fmt.Println("Created broadcast:", broadcast.Id)

// Send the broadcast to all contacts in the segment
sendParams := &resend.SendBroadcastRequest{
    BroadcastId: broadcast.Id,
}

sent, err := client.Broadcasts.Send(sendParams)
if err != nil {
    panic(err)
}

fmt.Println("Broadcast sent to segment")

See the Broadcasts guide for more details on sending email campaigns to segments.

Migration from Audiences

If you’re migrating from the legacy audiences system:

Audiences vs Segments

Old Approach (Audiences):

// Create audience-specific contact
contact, err := client.Contacts.Create(&resend.CreateContactRequest{
    Email:      "[email protected]",
    AudienceId: "aud-123", // Tied to specific audience
})

// Send broadcast
broadcast, err := client.Broadcasts.Create(&resend.CreateBroadcastRequest{
    AudienceId: "aud-123",
    From:       "[email protected]",
    Subject:    "Update",
    Html:       "<h1>Hello</h1>",
})

New Approach (Segments):

// Create global contact
contact, err := client.Contacts.Create(&resend.CreateContactRequest{
    Email: "[email protected]",
    // No AudienceId - contact is global
})

// Add to segment
_, err = client.Contacts.Segments.Add(&resend.AddContactSegmentRequest{
    ContactId: contact.Id,
    SegmentId: "seg-123",
})

// Send broadcast
broadcast, err := client.Broadcasts.Create(&resend.CreateBroadcastRequest{
    SegmentId: "seg-123", // Use SegmentId instead
    From:      "[email protected]",
    Subject:   "Update",
    Html:      "<h1>Hello</h1>",
})

The API still accepts audience_id for backward compatibility, but new code should use segment_id.

Best Practices

Use Descriptive Names

Give segments clear, descriptive names that indicate their purpose (e.g., “Premium Users”, “Newsletter Subscribers”).

Combine with Properties

Use contact properties along with segments for advanced targeting and personalization.

Keep Segments Organized

Regularly review and clean up unused segments to maintain organization.

Test Before Broadcasting

Test broadcast campaigns on a small segment before sending to larger audiences.

Next Steps

Contacts

Learn how to manage contacts

Broadcasts

Send email campaigns to segments

Segments Example

View the complete segments example

API Reference

View the complete Segments API reference

Get Started

Core Features

Advanced

Examples

Overview

Creating a Segment

Retrieving a Segment

Listing Segments

Deleting a Segment

Managing Contacts in Segments

Adding Contacts to Segments

Listing Contact’s Segments

Removing Contacts from Segments

Relationship to Contacts

Complete Example

Using Segments with Broadcasts

Migration from Audiences

Best Practices

Use Descriptive Names

Combine with Properties

Keep Segments Organized

Test Before Broadcasting

Next Steps

Contacts

Broadcasts

Segments Example

API Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Advanced

Examples

​Overview

​Creating a Segment

​Retrieving a Segment

​Listing Segments

​Deleting a Segment

​Managing Contacts in Segments

​Adding Contacts to Segments

​Listing Contact’s Segments

​Removing Contacts from Segments

​Relationship to Contacts

​Complete Example

​Using Segments with Broadcasts

​Migration from Audiences

​Best Practices

Use Descriptive Names

Combine with Properties

Keep Segments Organized

Test Before Broadcasting

​Next Steps

Contacts

Broadcasts

Segments Example

API Reference

Build docs developers (and LLMs) love

Overview

Creating a Segment

Retrieving a Segment

Listing Segments

Deleting a Segment

Managing Contacts in Segments

Adding Contacts to Segments

Listing Contact’s Segments

Removing Contacts from Segments

Relationship to Contacts

Complete Example

Using Segments with Broadcasts

Migration from Audiences

Best Practices

Next Steps