Create a Segment via the API

Create an AhaSend segment from a name, rules and a time zone. AhaSend then finds its members and keeps them up to date as your contacts and campaigns change.

POST /v2/accounts/{account_id}/segments

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()

  listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
  campaignID := uuid.MustParse("22222222-2222-4222-8222-222222222222")

  // Contacts in Germany, confirmed on the list, who opened the campaign or
  // opened at least 3 campaigns in the last 90 days. A group holds
  // conditions only.
  definition := common.SegmentDefinition{
    SchemaVersion: common.SegmentSchemaVersion,
    Match:         common.SegmentMatchAll,
    Conditions: []common.SegmentRule{
      {Condition: &common.SegmentCondition{
        Field: "attributes.country",
        Op:    common.SegmentOpEqual,
        Value: &common.SegmentValue{String: ahasend.String("DE")},
      }},
      {Condition: &common.SegmentCondition{
        Field: common.SegmentFieldList,
        Op:    common.SegmentOpIn,
        Value: &common.SegmentValue{String: ahasend.String(listID.String())},
      }},
      {Group: &common.SegmentGroup{
        Match: common.SegmentMatchAny,
        Conditions: []common.SegmentCondition{
          {
            Field: common.SegmentFieldCampaign,
            Op:    common.SegmentOpOpened,
            Value: &common.SegmentValue{String: ahasend.String(campaignID.String())},
          },
          {
            Field: common.SegmentFieldCampaignCount,
            Op:    common.SegmentOpOpenedAtLeast,
            Value: &common.SegmentValue{Count: &common.SegmentCampaignCount{Count: 3, Since: "90 days ago"}},
          },
        },
      }},
    },
  }

  // The SDK sends a fresh Idempotency-Key with this POST and reuses it on
  // its own retries, so a retried request creates no second segment.
  response, _, err := client.SegmentsAPI.CreateSegment(ctx, accountID, requests.CreateSegmentRequest{
    Name:       "Engaged German customers",
    Definition: definition,
    Timezone:   ahasend.String("Europe/Berlin"),
  })
  if err != nil {
    log.Fatalf("Error creating segment: %v", err)
  }
  // A new segment is building until its members are found.
  fmt.Printf("Created segment %s (%s)\n", response.ID, response.State)
}

201

{
  "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"
}

The AhaSend API creates one segment and starts to find its members. Access requires segments:write.

A new segment is building until its members are found. A large account can take some minutes. A campaign that uses the segment cannot be sent until the segment is ready. See States. To see what a definition matches before you save it, use Preview Segment.

Fields:

• name is required. The API trims it, and it must then have 1 to 255 characters. Names do not have to be unique in an account.
• description can have up to 1,000 characters after it is trimmed. Without it, or with null, the description is empty.
• definition is required. See Definitions.
• timezone is an IANA time zone, such as Europe/Berlin. Without it, or with null or an empty string, the segment uses UTC.
• A field that you cannot write is refused with 400, and the message names it.

Refusals:

• A refused definition answers 400, and the message names each problem by its path, such as conditions[0].field: the account has no contact field "city". An unknown time zone also answers 400.
• The API answers 409 when the account already has 100 segments, or when a list or campaign that the definition names is being changed. See Conflicts.

This operation accepts an Idempotency-Key header. Unlike most operations, it stores only a 2xx answer: a 4xx releases the key, so a retry with the same key runs again. See Idempotency.

Related Guides

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

Headers

Idempotency-Key · string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time secret_key, so successful encrypted replay responses for those operations expire after 5 minutes.

Maximum string length: 255

Path Parameters

account_id · string<uuid> · required

Account ID

Body

application/json

A new segment. A property that is not writable is rejected with 400 naming it.

name · string · required

Trimmed before it is measured and stored; a name that is empty after trimming is rejected.

Required string length: 1 - 255

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" }
        }
      ]
    }
  ]
}

description · string | null

Trimmed before it is stored. Null and omission both store an empty description.

Maximum string length: 1000

timezone · string | null

The IANA time zone, such as Europe/Berlin, that relative times and days are read in. Null, omission and an empty string all store UTC.

Response

201

application/json

Segment created

A saved set of rules over the account's contacts, and the contacts that match them.

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.