Skip to main content
POST
AhaSend Go SDK
The AhaSend API creates one list. Access requires lists:write. Lists are static, private and single opt-in. A new list has no members, so its contact_count is 0. To add contacts, use Add or Update a List Contact or Batch Add List Contacts. 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, the description is empty.
  • tags: the API trims each tag, drops empty tags and merges duplicates. At most 50 tags can remain. A null tag is refused.
  • A field that you cannot write is refused with 400, and the message names it.
This operation accepts an Idempotency-Key header. A retry with the same key replays the stored response for 24 hours. 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

The writable list projection. A property that is not writable is rejected with 400 naming it.

name
string
required

Trimmed before it is measured and stored. The bound counts characters rather than bytes, and a name that is empty after trimming is rejected.

Required string length: 1 - 255
description
string | null

Trimmed before it is measured and stored. The bound counts characters rather than bytes. Null and omission both store an empty description.

Maximum string length: 1000
tags
string[] | null

Each tag is trimmed, empty tags are dropped, and duplicates are collapsed; at most 50 tags may survive that normalization. A null element is rejected rather than read as an empty string. Null and omission both store an empty array.

Response

List created successfully

A static, private, single opt-in container of contacts, and the unit a campaign targets.

object
enum<string>
required

Object type identifier

Available options:
contact_list
id
string<uuid>
required

Unique identifier for the list

created_at
string<date-time>
required

When the list was created

updated_at
string<date-time>
required

When the list was last updated

name
string
required

List name; names are not unique within an account

description
string
required

Free-text description; empty when none was given

tags
string[]
required

Always present; an empty array when the list carries no tags

contact_count
integer
required

The list's subscribers: the members a campaign to this list would reach. A member counts when its membership is confirmed and the contact is enabled, not unsubscribed from everything, and not found invalid by validation. It is the same number the dashboard shows.

Required range: x >= 0