Contacts

Create, search, and manage contacts and their labels.

ContactsResource

ContactsResource(http)

Bases: BaseResource

Synchronous contacts resource.

Initialize contacts resource with nested labels resource.

list

list(account_id: int, page: int = 1) -> list[Contact]

List contacts with pagination.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
page	int	Page number (default: 1)	1

Returns:

Type	Description
list[Contact]	List of Contact objects

Examples:

>>> contacts = client.contacts.list(account_id=1, page=1)
... for contact in contacts:
... print(contact.name, contact.email)

search

search(account_id: int, query: str) -> list[Contact]

Search contacts.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
query	str	Search query string	required

Returns:

Type	Description
list[Contact]	List of matching Contact objects

Examples:

>>> contacts = client.contacts.search(account_id=1, query="john@example.com")

get

get(account_id: int, contact_id: int) -> Contact

Get contact details.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
Contact	Contact object

Examples:

>>> contact = client.contacts.get(account_id=1, contact_id=100)

create

create(
    account_id: int, inbox_id: int, **kwargs: Any
) -> ContactCreateResponse

Create a new contact.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
inbox_id	int	The inbox ID to associate contact with	required
**kwargs	Any	Contact attributes (name, email, phone_number, etc.)	{}

Returns:

Type	Description
ContactCreateResponse	ContactCreateResponse with contact and contact_inbox

Examples:

>>> result = client.contacts.create(
... account_id=1,
... inbox_id=5,
... name="John Doe",
... email="john@example.com",
... )
... print(result.contact.id, result.contact_inbox.source_id)

update

update(
    account_id: int, contact_id: int, **kwargs: Any
) -> Contact

Update contact.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required
**kwargs	Any	Contact attributes to update	{}

Returns:

Type	Description
Contact	Updated Contact object

Examples:

>>> contact = client.contacts.update(
... account_id=1,
... contact_id=100,
... name="Jane Doe",
... custom_attributes={"plan": "premium"}
... )

delete

delete(account_id: int, contact_id: int) -> None

Delete contact.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Examples:

>>> client.contacts.delete(account_id=1, contact_id=100)

conversations

conversations(
    account_id: int, contact_id: int
) -> list[Conversation]

Get contact conversations.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
list[Conversation]	List of Conversation objects for this contact

Examples:

>>> conversations = client.contacts.conversations(account_id=1, contact_id=100)

merge

merge(
    account_id: int,
    base_contact_id: int,
    mergee_contact_id: int,
) -> Contact

Merge two contacts. The mergee is deleted; the base contact is kept.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
base_contact_id	int	ID of the contact that remains after the merge	required
mergee_contact_id	int	ID of the contact that is merged in and deleted	required

Returns:

Type	Description
Contact	The resulting merged Contact object

Examples:

>>> contact = client.contacts.merge(
...     account_id=1,
...     base_contact_id=100,
...     mergee_contact_id=200
... )

contactable_inboxes

contactable_inboxes(
    account_id: int, contact_id: int
) -> list[dict]

Get inboxes that a contact can be reached through.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
list[dict]	List of dicts with 'source_id' and 'inbox' keys

Examples:

>>> inboxes = client.contacts.contactable_inboxes(account_id=1, contact_id=100)
... for item in inboxes:
...     print(item["source_id"], item["inbox"]["name"])

---

ContactLabelsResource

ContactLabelsResource(http: HTTPClient)

Bases: BaseResource

Nested resource for managing contact labels.

list

list(account_id: int, contact_id: int) -> list[str]

List contact labels.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
list[str]	List of label strings

Examples:

>>> labels = client.contacts.labels.list(account_id=1, contact_id=100)

add

add(
    account_id: int, contact_id: int, labels: list[str]
) -> list[str]

Add/replace labels on contact.

IMPORTANT: This overwrites existing labels, does not append.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required
labels	list[str]	List of label strings to set	required

Returns:

Type	Description
list[str]	Updated list of labels

Examples:

>>> labels = client.contacts.labels.add(
... account_id=1,
... contact_id=100,
... labels=["vip", "priority"]
... )

---

AsyncContactsResource

AsyncContactsResource(http)

Bases: AsyncBaseResource

Asynchronous contacts resource.

Initialize async contacts resource with nested labels resource.

list async

list(account_id: int, page: int = 1) -> list[Contact]

List contacts with pagination (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
page	int	Page number	1

Returns:

Type	Description
list[Contact]	List of Contact objects

search async

search(account_id: int, query: str) -> list[Contact]

Search contacts (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
query	str	Search query string	required

Returns:

Type	Description
list[Contact]	List of matching Contact objects

get async

get(account_id: int, contact_id: int) -> Contact

Get contact details (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
Contact	Contact object

create async

create(
    account_id: int, inbox_id: int, **kwargs: Any
) -> ContactCreateResponse

Create a new contact (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
inbox_id	int	The inbox ID	required
**kwargs	Any	Contact attributes	{}

Returns:

Type	Description
ContactCreateResponse	ContactCreateResponse with contact and contact_inbox

update async

update(
    account_id: int, contact_id: int, **kwargs: Any
) -> Contact

Update contact (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required
**kwargs	Any	Contact attributes to update	{}

Returns:

Type	Description
Contact	Updated Contact object

delete async

delete(account_id: int, contact_id: int) -> None

Delete contact (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

conversations async

conversations(
    account_id: int, contact_id: int
) -> list[Conversation]

Get contact conversations (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
list[Conversation]	List of Conversation objects

merge async

merge(
    account_id: int,
    base_contact_id: int,
    mergee_contact_id: int,
) -> Contact

Merge two contacts (async). The mergee is deleted; the base is kept.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
base_contact_id	int	ID of the contact that remains after the merge	required
mergee_contact_id	int	ID of the contact that is merged in and deleted	required

Returns:

Type	Description
Contact	The resulting merged Contact object

contactable_inboxes async

contactable_inboxes(
    account_id: int, contact_id: int
) -> list[dict]

Get inboxes that a contact can be reached through (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
list[dict]	List of dicts with 'source_id' and 'inbox' keys

---

AsyncContactLabelsResource

AsyncContactLabelsResource(http: AsyncHTTPClient)

Bases: AsyncBaseResource

Async nested resource for managing contact labels.

list async

list(account_id: int, contact_id: int) -> list[str]

List contact labels (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required

Returns:

Type	Description
list[str]	List of label strings

add async

add(
    account_id: int, contact_id: int, labels: list[str]
) -> list[str]

Add/replace labels on contact (async).

IMPORTANT: This overwrites existing labels, does not append.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
contact_id	int	The contact ID	required
labels	list[str]	List of label strings to set	required

Returns:

Type	Description
list[str]	Updated list of labels