List Contacts

Retrieve a list of contacts from your audience or global contacts

Methods

List

func (s *ContactsSvcImpl) List(options *ListContactsOptions) (ListContactsResponse, error)

Retrieves a list of contacts.

ListWithContext

func (s *ContactsSvcImpl) ListWithContext(ctx context.Context, options *ListContactsOptions) (ListContactsResponse, error)

Retrieves a list of contacts with context support.

Parameters

ListContactsOptions

audience_id · string

Optional - Omit for global contacts. Include to list audience-specific contacts.

limit · *int

Maximum number of contacts to return per page

after · *string

Cursor for pagination - retrieve results after this cursor

before · *string

Cursor for pagination - retrieve results before this cursor

Response

ListContactsResponse

object · string

Object type (“list”)

data · []Contact

Array of contact objects. Each contact contains:

• id (string): Contact identifier
• email (string): Email address
• object (string): Object type
• first_name (string): First name
• last_name (string): Last name
• created_at (string): Creation timestamp
• unsubscribed (bool): Unsubscribe status
• properties (map[string]any): Custom properties (global contacts only)

has_more · bool

Whether there are more results available for pagination

Examples

List All Global Contacts

package main

import (
    "fmt"
    "github.com/resend/resend-go/v2"
)

func main() {
    client := resend.NewClient("re_123456789")

    options := &resend.ListContactsOptions{}

    contacts, err := client.Contacts.List(options)
    if err != nil {
        panic(err)
    }

    fmt.Println("Total contacts:", len(contacts.Data))
    for _, contact := range contacts.Data {
        fmt.Printf("- %s (%s)\n", contact.Email, contact.FirstName)
    }
}

List with Pagination

limit := 20

options := &resend.ListContactsOptions{
    Limit: &limit,
}

contacts, err := client.Contacts.List(options)
if err != nil {
    panic(err)
}

fmt.Println("Contacts:", len(contacts.Data))
fmt.Println("Has more:", contacts.HasMore)

List Audience Contacts

options := &resend.ListContactsOptions{
    AudienceId: "aud_123456",
}

contacts, err := client.Contacts.List(options)
if err != nil {
    panic(err)
}

Paginate Through All Contacts

ctx := context.Background()

var allContacts []resend.Contact
limit := 50
after := ""

for {
    options := &resend.ListContactsOptions{
        Limit: &limit,
    }
    
    if after != "" {
        options.After = &after
    }
    
    response, err := client.Contacts.ListWithContext(ctx, options)
    if err != nil {
        panic(err)
    }
    
    allContacts = append(allContacts, response.Data...)
    
    if !response.HasMore {
        break
    }
    
    // Get the last contact ID as cursor for next page
    if len(response.Data) > 0 {
        after = response.Data[len(response.Data)-1].Id
    }
}

fmt.Println("Total contacts:", len(allContacts))

Notes

• Omit AudienceId to list global contacts
• Include AudienceId to list audience-specific contacts
• Use Limit, After, and Before for pagination
• The HasMore field indicates if additional pages are available