These commands need CLI v0.4.0 or later. Check your version with
ahasend --version, and upgrade if it is older.Prerequisites
Authenticate with a full API key. Segment tasks need these scopes:
The shell examples need Bash and jq.
A segment’s members are the contacts that match its rules, whatever their consent. A campaign to the segment reaches only the members who can get marketing email; see members and reachable contacts. A segment is
building while AhaSend finds its members, ready when they follow its rules, and failed when they could not be found. A campaign to a segment cannot be sent until the segment is ready; see segment states.
Write a Definition File
segments create, segments update and segments preview read a segment’s rules from --definition-file, a JSON file that holds one segment definition in the API’s shape. Save this file as engaged.json. It matches the contacts whose email address ends with @example.com and who were created in the last 30 days or opened at least 3 campaigns in the last 90 days:
engaged.json
all or any of its conditions. An entry of its conditions that has a match key is a group, which matches all or any of its own conditions; a group cannot hold a group. Any other entry is a condition, which compares a field with an operator, op, and a value. Definitions lists the fields, among them your own contact fields, lists and campaigns, with their operators and values and the limits on conditions.
A definition’s relative times, such as 30 days ago, and its days are read in the segment’s time zone: the IANA time zone, such as Europe/Berlin, that --timezone gives. A segment created without --timezone uses UTC, and segments update changes the time zone only when you give --timezone. segments preview --timezone reads the definition it tries the same way. See Time Zone.
The CLI checks the shape of the file before any request is sent. A mistake fails with exit code 4 and an error that names its place in the file:
- The file holds one JSON object. A file that is empty or is not JSON fails with
--definition-file is not JSON: <reason>, and other JSON with--definition-file must be a JSON object, the segment definition. - An object holds only the keys of its kind, each once:
schema_version,matchandconditionsin the definition,matchandconditionsin a group,field,opandvaluein a condition, andcountandsincein the count that acampaign_countcondition takes as its value. schema_versionandcountare integers written without a fraction or exponent;match,field,opandsinceare strings;conditionsis an array of objects. Avalueis a string, a number,true,false,nullor a count, and a whole number must lie between -2^53 and 2^53.- A group inside a group fails with
--definition-file: conditions[1].conditions[0] is a group inside a group, which the API does not allow.
Preview a Definition
segments preview tries a definition without saving anything. It shows how many contacts the definition matches now, whatever their consent, and up to 10 of them:
Count: not counted in time; the contacts are shown either way. Table output shows the contacts as a table under the count. CSV output has the header count,email,contact_id and one row per contact, each with the count, whose cell is empty when the API gave none; without contacts, it has one row, with the count alone.
Create a Test Segment
Save these commands in one Bash script, and run it in the folder that holdsengaged.json. The script creates a test segment, and later examples on this page use the same segment.
building until its members are found, which can take some minutes on a large account. An account has at most 100 segments. With --idempotency-key, a retry with the same key creates no second segment; see Idempotency.
segments get shows the segment’s state, the reason a failed segment failed, and its definition: as indented JSON in table and plain output, and as compact JSON in the definition column of CSV output. Members counts every contact that matches the rules, whatever its consent, and Marketable counts those a campaign to the segment alone would reach. Marketable is unknown in table and plain output, and an empty cell in CSV output, while the segment is not ready and when the API cannot count the members within 10 seconds.
segments list lists the account’s segments, newest first. Table output shows each segment’s name, ID, state, member count, and when it was updated. Plain and CSV output add the description, the failure reason, the time zone, when the members were last checked, the creation time and the definition. Pages work as Lists and Pagination describes.
To send a campaign to a segment, or leave its members out, give the segment’s ID to campaigns create or campaigns update; see Choose the Audience.
List the Members
Continue the script.segments members lists a segment’s members by contact ID, from the lowest:
building, its members may still follow its previous rules. To see the segments one contact is a member of, use ahasend contacts segments.
Update the Test Segment
Continue the script.update sends only the flags you give, and needs at least one.
--description "" clears the description, and --timezone "" sets UTC. --definition-file replaces the rules as a whole.
A change of the definition or the time zone builds the segment’s members again, and the segment is building until that ends. Any update of a failed segment builds it again. A change of only the name or the description of any other segment leaves its members and its state as they are.
An update or a delete that meets another change of the segment fails with HTTP 409, The segment is being updated. Try again in a minute., and exit code 1. Run the command again a minute later; see Conflicts.
Delete the Test Segment
Finish the script by deleting the segment it created.ahasend segments list and delete it with segments delete.
Deleting a segment does not delete its contacts; its members are removed shortly after. The API refuses to delete a segment while a campaign that still needs it, to send to its members or to leave them out, refers to it. A segment in turn keeps the lists, campaigns and contact fields that its rules name from being deleted until you change or delete the segment; see delete a segment.
segments delete asks for confirmation first; see prompts.
Command Flags
These flags come from the CLI’s--help. All commands also accept the global flags.

