Preview a Segment via the API

Try AhaSend segment rules without saving them: get the number of contacts that the rules match now, and up to 10 of the matching contacts.

POST /v2/accounts/{account_id}/segments/preview

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/common"
  "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()

  // Nothing is saved. Count is nil when the contacts cannot be counted
  // within 10 seconds.
  response, _, err := client.SegmentsAPI.PreviewSegment(ctx, accountID, requests.PreviewSegmentRequest{
    Definition: common.SegmentDefinition{
      SchemaVersion: common.SegmentSchemaVersion,
      Match:         common.SegmentMatchAll,
      Conditions: []common.SegmentRule{
        {Condition: &common.SegmentCondition{
          Field: common.SegmentFieldCreatedAt,
          Op:    common.SegmentOpAfter,
          Value: &common.SegmentValue{String: ahasend.String("30 days ago")},
        }},
      },
    },
  })
  if err != nil {
    log.Fatalf("Error previewing segment: %v", err)
  }
  if response.Count != nil {
    fmt.Printf("%d contacts match\n", *response.Count)
  }
  for _, contact := range response.Contacts {
    fmt.Println(contact.Email)
  }
}

200

{
  "object": "segment_preview",
  "count": 1,
  "contacts": [
    {
      "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "[e-mail]"
    }
  ]
}

The AhaSend API counts the contacts that a definition matches now, and returns up to 10 of them. Nothing is saved. Access requires segments:read and contacts:read, because a preview reads contacts by any rule.

Request:

• definition is required. It follows the same rules as in Create Segment. See Definitions.
• timezone is the IANA time zone that relative times and days are read in. Without it, or with null or an empty string, they are read in UTC.

Response:

• count is the number of contacts that match, whatever their consent. A campaign can reach fewer of them. See Members and reachable contacts.
• The count stops after 10 seconds, and count is then null.
• contacts holds up to 10 matching contacts, in no particular order, each with contact_id and email. They are a separate read, so they come back also when count is null. contacts is empty when they cannot be read within 10 seconds.

A refused definition or an unknown time zone answers 400, and the message names each problem.

Related Guides

• API authentication, Permission scopes, Create 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

Body

application/json

A definition to try. Nothing is saved.

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 | null

The IANA time zone that relative times and days are read in. Null, omission and an empty string all read them in UTC.

Response

200

application/json

What the definition matches now

object · enum<string> · required

Object type identifier

Available options: segment_preview

count · integer | null · required

The contacts the definition matches now, whatever their consent. Null when they cannot be counted within 10 seconds.

Required range: x >= 0

contacts · object[] · required

Up to 10 of the matching contacts, in no particular order. They are returned also when count is null, and are empty when they cannot be read within 10 seconds.

Maximum array length: 10

Show child attributes