Get a Segment via the API

Retrieve one AhaSend segment by ID with its rules, state and member count, and marketable_count, the members that a campaign to the segment would reach.

GET /v2/accounts/{account_id}/segments/{segment_id}

AhaSend Go SDK

Go

package main

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

  "github.com/AhaSend/ahasend-go/api"
  "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()

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

  response, _, err := client.SegmentsAPI.GetSegment(ctx, accountID, segmentID)
  if err != nil {
    log.Fatalf("Error getting segment: %v", err)
  }
  // MarketableCount is nil while the segment is not ready.
  if response.MarketableCount != nil {
    fmt.Printf("%s: %d members, %d a campaign would reach\n", response.Name, response.MemberCount, *response.MarketableCount)
  } else {
    fmt.Printf("%s: %d members (%s)\n", response.Name, response.MemberCount, response.State)
  }
}

200

{
  "object": "segment",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "description": "<string>",
  "definition": {
    "schema_version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "attributes.country",
        "op": "equal",
        "value": "DE"
      },
      {
        "field": "created_at",
        "op": "after",
        "value": "30 days ago"
      },
      {
        "field": "list",
        "op": "in",
        "value": "6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b"
      },
      {
        "match": "any",
        "conditions": [
          {
            "field": "campaign",
            "op": "opened",
            "value": "9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b"
          },
          {
            "field": "any_campaign",
            "op": "clicked",
            "value": "14 days ago"
          },
          {
            "field": "campaign_count",
            "op": "opened_at_least",
            "value": {
              "count": 3,
              "since": "90 days ago"
            }
          }
        ]
      }
    ]
  },
  "timezone": "<string>",
  "state": "building",
  "failure_reason": "<string>",
  "member_count": 1,
  "last_evaluated_at": "2023-11-07T05:31:56Z",
  "marketable_count": 1
}

The AhaSend API returns one segment of the account. Access requires segments:read.

• member_count is the number of contacts that match the rules, whatever their consent.
• marketable_count is the number of members that a campaign to this segment alone would reach. See Members and reachable contacts for what it counts. It is null while the segment is not ready, and when the members cannot be counted within 10 seconds.
• state is building, ready or failed. A failed segment gives the reason in failure_reason. See States.
• last_evaluated_at is the time the members were last checked against the whole account. It is null until the first build ends.

To read the members, use List Segment Contacts. A segment that was deleted answers 404.

Related Guides

• API authentication, Permission scopes, Update Segment.
• Segments 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

segment_id · string<uuid> · required

Segment ID

Response

200

application/json

The segment

A segment as Get Segment returns it, with marketable_count.

object · enum<string> · required

Object type identifier

Available options: segment

id · string<uuid> · required

Unique identifier for the segment

created_at · string<date-time> · required

When the segment was created

updated_at · string<date-time> · required

When the segment was last saved

name · string · required

Segment name; names are not unique within an account

description · string · required

Free-text description; empty when none was given

definition · object · required

The rules of a segment. The root group holds conditions and groups; a group holds conditions only, so groups nest one level deep. A definition has at most 50 conditions in all, and at most 5 of them are campaign, any_campaign or campaign_count conditions. An unknown key, or a schema_version other than 1, is refused. A refused definition is answered with 400 and a message that names each problem by its path, such as conditions[3].value.

Show child attributes

Example:

{
  "schema_version": 1,
  "match": "all",
  "conditions": [
    {
      "field": "attributes.country",
      "op": "equal",
      "value": "DE"
    },
    {
      "field": "created_at",
      "op": "after",
      "value": "30 days ago"
    },
    {
      "field": "list",
      "op": "in",
      "value": "6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b"
    },
    {
      "match": "any",
      "conditions": [
        {
          "field": "campaign",
          "op": "opened",
          "value": "9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b"
        },
        {
          "field": "any_campaign",
          "op": "clicked",
          "value": "14 days ago"
        },
        {
          "field": "campaign_count",
          "op": "opened_at_least",
          "value": { "count": 3, "since": "90 days ago" }
        }
      ]
    }
  ]
}

timezone · string · required

The IANA time zone that relative times and days in the definition are read in

state · enum<string> · required

• building: the members are being found for the current definition. A campaign that uses the segment cannot be sent until it is ready.
• ready: the members follow the current definition.
• failed: the members could not be found; failure_reason says why. Any update of the segment, {} included, builds it again.

Available options: building, ready, failed

failure_reason · string | null · required

Why the segment failed. Null unless state is failed.

member_count · integer · required

The contacts that match the rules, whatever their consent. A campaign reaches only those of them who may get marketing email; Get Segment counts them as marketable_count.

Required range: x >= 0

last_evaluated_at · string<date-time> | null · required

When the members were last checked against the whole account. Null until the first build ends.

marketable_count · integer | null · required

The members a campaign to this segment alone would reach: enabled, not unsubscribed, not found invalid, and either confirmed on at least one list or on no list at all. A contact who unsubscribed from or complained on every list they were on, or has not confirmed a double opt-in, is not counted. Null while state is not ready, since no campaign sends to the segment then, and null when they cannot be counted within 10 seconds.

Required range: x >= 0