Add or Update a List Contact via the API

Add an existing AhaSend contact to a list, or change its per-list subscription status to confirmed, unconfirmed or unsubscribed. No contact is created.

PUT /v2/accounts/{account_id}/lists/{list_id}/contacts/{id_or_email}

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

  listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")

  // Record that the contact unsubscribed from this list. Setting confirmed
  // would subscribe them again, so only do that when they asked for it.
  response, _, err := client.ListsAPI.UpsertListContact(ctx, accountID, listID, "[e-mail]", requests.UpsertListContactRequest{
    SubscriptionStatus: ahasend.String(requests.ListContactStatusUnsubscribed),
  })
  if err != nil {
    log.Fatalf("Error updating the list membership: %v", err)
  }
  fmt.Printf("%s is %s\n", response.Email, response.SubscriptionStatus)
}

200

{
  "object": "list_contact",
  "list_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "[e-mail]",
  "subscription_status": "unconfirmed",
  "subscribed_at": "2023-11-07T05:31:56Z",
  "unsubscribed_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "contact": {
    "object": "contact",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "email": "[e-mail]",
    "first_name": "<string>",
    "last_name": "<string>",
    "status": "enabled",
    "status_reason": "<string>",
    "unsubscribed": true,
    "unsubscribed_at": "2023-11-07T05:31:56Z",
    "attributes": {},
    "validation_status": "unvalidated",
    "last_validated_at": "2023-11-07T05:31:56Z"
  },
  "list": {
    "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>"
    ]
  }
}

The AhaSend API adds one existing contact to one list, or changes the membership that is already there. It returns the membership in both cases. Access requires lists:write.

{id_or_email} is the contact ID or its email address. Percent-encode an email address exactly once. See Name a contact in the path. This operation does not create a contact. To create one, use Create Contact.

Status:

• The body can hold only subscription_status: confirmed, unconfirmed or unsubscribed. An empty object is allowed.
• A new membership is confirmed, unless the body names another status.
• For a membership that already exists, a body with no status changes nothing. To subscribe a contact again after an unsubscribe, name confirmed.
• When the body names the status that the membership already has, nothing changes, updated_at included. So a retry gives the same result.
• confirmed sets subscribed_at and clears unsubscribed_at. unsubscribed sets unsubscribed_at and keeps subscribed_at. unconfirmed sets neither.

Refusals:

• complained cannot be written. A body that names it is refused with 400.
• A membership that is complained cannot change. A request for it answers 409 and changes nothing, also a request with no status.
• A list or a contact that does not exist answers 404, and the message says which.

Related Guides

• API authentication, Permission scopes, Batch Add List Contacts.
• Memberships, 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.

Path Parameters

account_id · string<uuid> · required

Account ID

list_id · string<uuid> · required

List ID

id_or_email · string · required

Contact UUID or email address. Percent-encode an email exactly once as a path segment; SDK callers pass the raw email value.

Body

application/json

Names at most subscription_status. An empty object is legal and names no status: on a new membership that means confirmed, and on one that already exists it leaves the stored status exactly as it is. A property that is not writable is rejected with 400 naming it.

subscription_status · enum<string> | null

Null and omission are one case and name no status. complained is the mailbox provider's verdict rather than the caller's and is rejected with 400.

Available options: confirmed, unconfirmed, unsubscribed, null

Response

200

application/json

The membership, whether this request created it or updated one

One contact's membership of one list. It carries no id of its own: a membership is addressed by the (list_id, contact_id) pair.

object · enum<string> · required

Object type identifier

Available options: list_contact

list_id · string<uuid> · required

The list this membership is on

contact_id · string<uuid> · required

The contact this membership belongs to

email · string<email> · required

The contact's normalized email address

subscription_status · enum<string> · required

Per-list consent, independent of the contact's account-wide unsubscribed flag. complained is the mailbox provider's verdict and is never writable.

Available options: unconfirmed, confirmed, unsubscribed, complained

subscribed_at · string<date-time> | null · required

When consent was given. Set when the membership becomes confirmed and left alone afterwards, so it records when consent was given rather than when it was last re-asserted.

unsubscribed_at · string<date-time> | null · required

When the membership became unsubscribed, or when the complaint landed for a complained membership. Cleared when the membership becomes confirmed again.

created_at · string<date-time> · required

When the membership was created

updated_at · string<date-time> · required

When the membership was last updated

contact · object

The whole contact. Present only on GET /v2/accounts/{account_id}/lists/{list_id}/contacts with include_contacts=true.

Show child attributes

list · object

The list this membership is on. Present only on GET /v2/accounts/{account_id}/contacts/{id_or_email}/lists.

Show child attributes