AhaSend Go SDK
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)
}
}import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// Nothing is saved. count is null when the contacts cannot be counted within 10 seconds.
const preview = await client.segments.preview({
definition: {
schema_version: 1,
match: "all",
conditions: [{ field: "created_at", op: "after", value: "30 days ago" }],
},
});
console.log("Segment previewed.", { count: preview.count, shown: preview.contacts.length });
curl --request POST \
--url https://api.ahasend.com/v2/accounts/{account_id}/segments/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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>"
}
'import requests
url = "https://api.ahasend.com/v2/accounts/{account_id}/segments/preview"
payload = {
"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>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ahasend.com/v2/accounts/{account_id}/segments/preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.post("https://api.ahasend.com/v2/accounts/{account_id}/segments/preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"definition\": {\n \"schema_version\": 1,\n \"match\": \"all\",\n \"conditions\": [\n {\n \"field\": \"attributes.country\",\n \"op\": \"equal\",\n \"value\": \"DE\"\n },\n {\n \"field\": \"created_at\",\n \"op\": \"after\",\n \"value\": \"30 days ago\"\n },\n {\n \"field\": \"list\",\n \"op\": \"in\",\n \"value\": \"6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b\"\n },\n {\n \"match\": \"any\",\n \"conditions\": [\n {\n \"field\": \"campaign\",\n \"op\": \"opened\",\n \"value\": \"9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b\"\n },\n {\n \"field\": \"any_campaign\",\n \"op\": \"clicked\",\n \"value\": \"14 days ago\"\n },\n {\n \"field\": \"campaign_count\",\n \"op\": \"opened_at_least\",\n \"value\": {\n \"count\": 3,\n \"since\": \"90 days ago\"\n }\n }\n ]\n }\n ]\n },\n \"timezone\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ahasend.com/v2/accounts/{account_id}/segments/preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"definition\": {\n \"schema_version\": 1,\n \"match\": \"all\",\n \"conditions\": [\n {\n \"field\": \"attributes.country\",\n \"op\": \"equal\",\n \"value\": \"DE\"\n },\n {\n \"field\": \"created_at\",\n \"op\": \"after\",\n \"value\": \"30 days ago\"\n },\n {\n \"field\": \"list\",\n \"op\": \"in\",\n \"value\": \"6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b\"\n },\n {\n \"match\": \"any\",\n \"conditions\": [\n {\n \"field\": \"campaign\",\n \"op\": \"opened\",\n \"value\": \"9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b\"\n },\n {\n \"field\": \"any_campaign\",\n \"op\": \"clicked\",\n \"value\": \"14 days ago\"\n },\n {\n \"field\": \"campaign_count\",\n \"op\": \"opened_at_least\",\n \"value\": {\n \"count\": 3,\n \"since\": \"90 days ago\"\n }\n }\n ]\n }\n ]\n },\n \"timezone\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "segment_preview",
"count": 1,
"contacts": [
{
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "jsmith@example.com"
}
]
}{
"message": "conditions[0].field: the account has no contact field \"city\"; conditions[1].value: must be a list id"
}{
"message": "Error message"
}{
"message": "Error message"
}{
"message": "Error message"
}{
"message": "Error message"
}Segments
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
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)
}
}import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// Nothing is saved. count is null when the contacts cannot be counted within 10 seconds.
const preview = await client.segments.preview({
definition: {
schema_version: 1,
match: "all",
conditions: [{ field: "created_at", op: "after", value: "30 days ago" }],
},
});
console.log("Segment previewed.", { count: preview.count, shown: preview.contacts.length });
curl --request POST \
--url https://api.ahasend.com/v2/accounts/{account_id}/segments/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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>"
}
'import requests
url = "https://api.ahasend.com/v2/accounts/{account_id}/segments/preview"
payload = {
"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>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ahasend.com/v2/accounts/{account_id}/segments/preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.post("https://api.ahasend.com/v2/accounts/{account_id}/segments/preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"definition\": {\n \"schema_version\": 1,\n \"match\": \"all\",\n \"conditions\": [\n {\n \"field\": \"attributes.country\",\n \"op\": \"equal\",\n \"value\": \"DE\"\n },\n {\n \"field\": \"created_at\",\n \"op\": \"after\",\n \"value\": \"30 days ago\"\n },\n {\n \"field\": \"list\",\n \"op\": \"in\",\n \"value\": \"6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b\"\n },\n {\n \"match\": \"any\",\n \"conditions\": [\n {\n \"field\": \"campaign\",\n \"op\": \"opened\",\n \"value\": \"9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b\"\n },\n {\n \"field\": \"any_campaign\",\n \"op\": \"clicked\",\n \"value\": \"14 days ago\"\n },\n {\n \"field\": \"campaign_count\",\n \"op\": \"opened_at_least\",\n \"value\": {\n \"count\": 3,\n \"since\": \"90 days ago\"\n }\n }\n ]\n }\n ]\n },\n \"timezone\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ahasend.com/v2/accounts/{account_id}/segments/preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"definition\": {\n \"schema_version\": 1,\n \"match\": \"all\",\n \"conditions\": [\n {\n \"field\": \"attributes.country\",\n \"op\": \"equal\",\n \"value\": \"DE\"\n },\n {\n \"field\": \"created_at\",\n \"op\": \"after\",\n \"value\": \"30 days ago\"\n },\n {\n \"field\": \"list\",\n \"op\": \"in\",\n \"value\": \"6f1c2a52-8f2e-4d8e-9a3b-1c2d3e4f5a6b\"\n },\n {\n \"match\": \"any\",\n \"conditions\": [\n {\n \"field\": \"campaign\",\n \"op\": \"opened\",\n \"value\": \"9a2e7c41-0b3d-4f5e-8a6b-7c8d9e0f1a2b\"\n },\n {\n \"field\": \"any_campaign\",\n \"op\": \"clicked\",\n \"value\": \"14 days ago\"\n },\n {\n \"field\": \"campaign_count\",\n \"op\": \"opened_at_least\",\n \"value\": {\n \"count\": 3,\n \"since\": \"90 days ago\"\n }\n }\n ]\n }\n ]\n },\n \"timezone\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "segment_preview",
"count": 1,
"contacts": [
{
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "jsmith@example.com"
}
]
}{
"message": "conditions[0].field: the account has no contact field \"city\"; conditions[1].value: must be a list id"
}{
"message": "Error message"
}{
"message": "Error message"
}{
"message": "Error message"
}{
"message": "Error message"
}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:
definitionis required. It follows the same rules as in Create Segment. See Definitions.timezoneis the IANA time zone that relative times and days are read in. Without it, or withnullor an empty string, they are read inUTC.
countis 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
countis thennull. contactsholds up to 10 matching contacts, in no particular order, each withcontact_idandemail. They are a separate read, so they come back also whencountisnull.contactsis empty when they cannot be read within 10 seconds.
400, and the message names each problem.
Related Guides
- API authentication, Permission scopes, Create Segment.
- Segments API overview, API errors, API rate limits.
Authorizations
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
Body
application/json
A definition to try. Nothing is saved.
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
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" }
}
]
}
]
}
The IANA time zone that relative times and days are read in. Null, omission and an empty string all read them in UTC.
Response
What the definition matches now
Object type identifier
Available options:
segment_preview The contacts the definition matches now, whatever their consent. Null when they cannot be counted within 10 seconds.
Required range:
x >= 0Up 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:
10Show child attributes
Show child attributes