Create a List via the API

Create an AhaSend contact list with a name, a description and tags. A new list has no contacts, and list names do not have to be unique.

POST /v2/accounts/{account_id}/lists

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

  // The SDK sends a fresh Idempotency-Key with this POST and reuses it on
  // its own retries, so a retried request is not applied twice.
  response, _, err := client.ListsAPI.CreateList(ctx, accountID, requests.CreateListRequest{
    Name:        "Product updates",
    Description: ahasend.String("Monthly release notes"),
    Tags:        []string{"product"},
  })
  if err != nil {
    log.Fatalf("Error creating list: %v", err)
  }
  fmt.Printf("Created list %s\n", response.ID)
}

201

{
  "object": "contact_list",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "description": "<string>",
  "tags": [
    "<string>"
  ],
  "contact_count": 1
}

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.

Related Guides

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

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

201

application/json

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