List the Contacts on a List via the API

List the members of an AhaSend contact list with their per-list subscription status. Filter by status or email, and embed the whole contact.

GET /v2/accounts/{account_id}/lists/{list_id}/contacts

AhaSend Go SDK

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  "github.com/AhaSend/ahasend-go"
  "github.com/AhaSend/ahasend-go/api"
  "github.com/AhaSend/ahasend-go/models/requests"
  "github.com/google/uuid"
)

func main() {
  client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
  accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
  ctx := context.Background()

  listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")

  response, _, err := client.ListsAPI.GetListContacts(ctx, accountID, listID, requests.GetListContactsParams{
    SubscriptionStatus: ahasend.String(requests.ListContactStatusConfirmed),
  })
  if err != nil {
    log.Fatalf("Error listing list contacts: %v", err)
  }
  for _, member := range response.Data {
    fmt.Printf("%s %s\n", member.Email, member.SubscriptionStatus)
  }
}

200

{
  "object": "list",
  "data": [
    {
      "object": "list_contact",
      "list_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "[e-mail]",
      "subscription_status": "unconfirmed",
      "subscribed_at": "2023-11-07T05:31:56Z",
      "unsubscribed_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "contact": {
        "object": "contact",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "email": "[e-mail]",
        "first_name": "<string>",
        "last_name": "<string>",
        "status": "enabled",
        "status_reason": "<string>",
        "unsubscribed": true,
        "unsubscribed_at": "2023-11-07T05:31:56Z",
        "attributes": {},
        "validation_status": "unvalidated",
        "last_validated_at": "2023-11-07T05:31:56Z"
      },
      "list": {
        "object": "contact_list",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "description": "<string>",
        "tags": [
          "<string>"
        ]
      }
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "<string>",
    "previous_cursor": "<string>"
  }
}

The AhaSend API returns the members of one list, newest membership first. Access requires lists:read.

Each item is a membership with its subscription_status, the contact_id and the email address of the contact. See Memberships.

Filters:

• subscription_status is unconfirmed, confirmed, unsubscribed or complained. confirmed gives the members that a campaign to the list can reach, after the account-wide checks of the contact. See Lists.
• email matches one email address exactly, after it is trimmed and changed to lowercase. An empty value returns all members.
• include_contacts=true adds the whole contact to each item. It also needs the contacts:read scope. Without it, the request answers 403, also for a list that does not exist.

Pages use cursors: send after or before, not both. See Pagination.

Related Guides

• API authentication, Permission scopes, Batch Add List Contacts.
• Lists API overview, API errors, API rate limits.

Authorizations

Authorization · string · header · required

API key for authentication. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives.

Path Parameters

account_id · string<uuid> · required

Account ID

list_id · string<uuid> · required

List ID

Query Parameters

limit · integer · default: 100

Maximum number of memberships to return

Required range: 1 <= x <= 100

after · string

Cursor for the next page; cannot be combined with before

before · string

Cursor for the previous page; cannot be combined with after

subscription_status · enum<string>

Per-list consent filter

Available options: unconfirmed, confirmed, unsubscribed, complained

email · string<email>

Exact email filter. The value is normalized before it is compared, so one that is empty or all whitespace filters nothing and the full collection is returned. It is compared against the address as stored, so an address that was stored unnormalized renders normalized in this collection and is still not matched by this filter.

include_contacts · boolean

Embed the whole contact in every item. Requires the contacts:read scope in addition to lists:read.

Response

200

application/json

Paginated list memberships

object · enum<string> · required

Available options: list

data · object[] · required

Show child attributes

pagination · object · required

Show child attributes