Skip to main content
The AhaSend Contacts API manages the contacts of your account. This page explains what a contact is, how it relates to lists and segments, and the rules that apply to all contact operations.

​
Contacts, Lists and Segments

A contact is one person in your account, found by email address. Contacts are account-global: one contact has one email address, and one email address belongs to at most one contact in the account. The API trims the email address and changes it to lowercase before it stores it. A new contact is on no list. Campaigns send to lists and segments. A campaign to lists reaches a contact after you add it to a list with the Lists API, and each list membership has its own subscription_status. See Memberships. A segment finds its members by rules over the contact fields, so a campaign to a segment can also reach a contact on no list. A contact has two kinds of consent:
  • unsubscribed on the contact is account-wide. When it is true, campaigns do not send to the contact, from any list or segment. It does not change the contact’s memberships. A contact who unsubscribes from a campaign sent through a segment, or reports it as spam, gets unsubscribed: true.
  • subscription_status on a membership applies to one list only.
Contacts and suppressions are separate. Create Contact does not read or change suppressions, and a change to unsubscribed does not add or remove a suppression.

​
Contact Fields

​
Name a Contact in the Path

Operations on one contact take {id_or_email} in the path:
  • A value in UUID form is read as the contact ID.
  • Any other value is read as an email address. The API trims it and changes it to lowercase.
Percent-encode an email address exactly once as a path segment. For example, user+tag@example.com becomes user%2Btag%40example.com. The official SDKs encode the value for you, so pass them the email address as it is.

​
Attributes

You define the attribute keys and their types in the dashboard. A write must use a defined key, and its value must match the type: On create, an attribute value cannot be null. On update, the API merges the attributes object into the stored attributes, and a null value removes that key. Attributes that you read can also hold null, arrays or nested objects. Writes accept only the types above.

​
Pagination

List Contacts returns contacts 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 read the lists of a contact, you need lists:read. To read the segments of a contact, you need segments:read and contacts:read. See Permission scopes.

​
Idempotency

Create Contact and Batch Upsert Contacts accept an Idempotency-Key header. See Idempotency.

​
API Operations