Skip to main content
PUT
AhaSend Go SDK
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.

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

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.

list
object

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