Skip to main content
The AhaSend Lists API manages your contact lists and the contacts on them. A campaign sends to lists, so a list is how a contact gets marketing email. This page explains lists and memberships, and the rules that apply to all list operations.

​
Lists

A list is a static, private, single opt-in group of contacts, and the unit that a campaign targets. List names do not have to be unique in an account. contact_count is the number of subscribers that a campaign to the list would reach. It counts a member when:
  • Its membership is confirmed.
  • The contact is enabled.
  • The contact is not unsubscribed account-wide.
  • Email validation did not find the contact invalid.
It is the same number that the dashboard shows.

​
Memberships

A membership is one contact on one list. It has no ID of its own: you name it by the list ID and the contact. A contact can be on many lists, and each membership has its own subscription_status: subscribed_at is the time the membership became confirmed. A confirm of a membership that is already confirmed does not change it. unsubscribed_at is the time the membership became unsubscribed, or the time of the complaint. It is cleared when the membership becomes confirmed again. The per-list status and the account-wide unsubscribed flag of the contact are separate. Update Contact with unsubscribed: true stops campaigns to the contact on all lists, and leaves every membership status as it is.

​
Unsubscribe, Remove or Delete

To stop marketing email, unsubscribe the contact instead of removing it.

​
Pagination

List Lists, List Contacts on a List and List Contact’s Lists return items newest first. Each page gives pagination.has_more, pagination.next_cursor and pagination.previous_cursor. Send next_cursor as after for the next page, or previous_cursor as before for the previous page. You cannot send after and before together. limit is 1 to 100, and the default is 100.

​
Scopes

To remove a contact from a list, you need lists:write, not lists:delete. List Contacts on a List with include_contacts=true also needs contacts:read. See Permission scopes.

​
Idempotency

Create List and Batch Add List Contacts accept an Idempotency-Key header. See Idempotency.

​
API Operations