Skip to main content
POST
AhaSend Go SDK
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.

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.

Example:
​
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

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.

Example:
​
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.