helpscout.apis package

Submodules

helpscout.apis.conversations module

class helpscout.apis.conversations.Conversations[source]

Bases: helpscout.base_api.BaseApi

This represents the Conversations Endpoint.

The following aspects are implemented:

classmethod create(session, record, imported=False, auto_reply=False)[source]

Create a conversation.

Please note that conversation cannot be created with more than 100 threads, if attempted the API will respond with HTTP 412.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • record (helpscout.models.Conversation) – The conversation to be created.
  • imported (bool, optional) – The imported request parameter enables conversations to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When imported is set to True, no outgoing emails or notifications will be generated.
  • auto_reply (bool) – The auto_reply request parameter enables auto replies to be sent when a conversation is created via the API. When auto_reply is set to True, an auto reply will be sent as long as there is at least one customer thread in the conversation.
Returns:

Newly created conversation.
Return type:

helpscout.models.Conversation
classmethod create_attachment(session, attachment)[source]

Create an attachment.

An attachment must be sent to the API before it can be used in a thread. Use this method to create the attachment, then use the resulting hash when creating a thread.

Note that HelpScout only supports attachments of 10MB or lower.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • attachment (helpscout.models.Attachment) – The attachment to be created.
Returns:

The newly created attachment (hash

property only). Use this hash when associating the attachment with a new thread.
Return type:

helpscout.models.Attachment
classmethod create_thread(session, conversation, thread, imported=False)[source]

Create a conversation thread.

Please note that threads cannot be added to conversations with 100 threads (or more), if attempted the API will respond with HTTP 412.

Parameters:
  • conversation (helpscout.models.Conversation) – The conversation that the thread is being added to.
  • session (requests.sessions.Session) – Authenticated session.
  • thread (helpscout.models.Thread) – The thread to be created.
  • imported (bool, optional) – The imported request parameter enables conversations to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When imported is set to True, no outgoing emails or notifications will be generated.
Returns:

Conversation including newly created

thread.
Return type:

helpscout.models.Conversation
classmethod delete_attachment(session, attachment)[source]

Delete an attachment.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • attachment (helpscout.models.Attachment) – The attachment to be deleted.
Returns:

Nothing.
Return type:

NoneType
classmethod find_customer(session, mailbox, customer)[source]

Return conversations for a specific customer in a mailbox.

Parameters:
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod find_user(session, mailbox, user)[source]

Return conversations for a specific user in a mailbox.

Parameters:
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod get_attachment_data(session, attachment_id)[source]

Return a specific attachment’s data.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • attachment_id (int) – The ID of the attachment from which to get data.
Returns:

An attachment data singleton, if

existing. Otherwise None.
Return type:

helpscout.models.AttachmentData
classmethod list(session, mailbox)[source]

Return conversations in a mailbox.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • mailbox (helpscout.models.Mailbox) – Mailbox to list.
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod list_folder(session, mailbox, folder)[source]

Return conversations in a specific folder of a mailbox.

Parameters:
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod search(session, queries)[source]

Search for a conversation given a domain.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • queries (helpscout.models.Domain or iter) – The queries for the domain. If a Domain object is provided, it will simply be returned. Otherwise, a Domain object will be generated from the complex queries. In this case, the queries should conform to the interface in helpscout.domain.Domain.from_tuple().
Returns:

SearchCustomer iterator.
Return type:

RequestPaginator(output_type=helpscout.models.SearchCustomer)
classmethod update_thread(session, conversation, thread)[source]

Update a thread.

Parameters:
Returns:

Conversation including freshly

updated thread.
Return type:

helpscout.models.Conversation

helpscout.apis.customers module

class helpscout.apis.customers.Customers[source]

Bases: helpscout.base_api.BaseApi

This represents the Customers Endpoint.

The following aspects are implemented:

classmethod list(session, first_name=None, last_name=None, email=None, modified_since=None)[source]

List the customers.

Customers can be filtered on any combination of first name, last name, email, and modifiedSince.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • first_name (str, optional) – First name of customer.
  • last_name (str, optional) – Last name of customer.
  • email (str, optional) – Email address of customer.
  • modified_since (datetime.datetime, optional) – If modified after this date.
Returns:

Customers

iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Customer)
classmethod search(session, queries)[source]

Search for a customer given a domain.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • queries (helpscout.models.Domain or iter) – The queries for the domain. If a Domain object is provided, it will simply be returned. Otherwise, a Domain object will be generated from the complex queries. In this case, the queries should conform to the interface in helpscout.domain.Domain.from_tuple().
Returns:

SearchCustomer iterator.
Return type:

RequestPaginator(output_type=helpscout.models.SearchCustomer)

helpscout.apis.mailboxes module

class helpscout.apis.mailboxes.Mailboxes[source]

Bases: helpscout.base_api.BaseApi

This represents the Mailboxes Endpoint.

The following aspects are implemented:

classmethod get_folders(session, mailbox_or_id)[source]

List the folders for the mailbox.

Parameters:mailbox_or_id (helpscout.models.Mailbox or int) – Mailbox or the ID of the mailbox to get the folders for.
Returns:
Folders
iterator.
Return type:RequestPaginator(output_type=helpscout.models.Folder)
classmethod list(session)[source]

List the mailboxes.

Parameters:session (requests.sessions.Session) – Authenticated session.
Returns:
Mailboxes
iterator.
Return type:RequestPaginator(output_type=helpscout.models.Mailbox)

helpscout.apis.tags module

class helpscout.apis.tags.Tags[source]

Bases: helpscout.base_api.BaseApi

This represents the Tags Endpoint.

The following aspects are implemented:

  • List Tags (helpscout.apis.tags.Tags.list())

helpscout.apis.teams module

class helpscout.apis.teams.Teams[source]

Bases: helpscout.base_api.BaseApi

This represents the Teams Endpoint.

The following aspects are implemented:

classmethod get(session, team_id)[source]

Return a specific team.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • team_id (int) – The ID of the team to get.
Returns:

A person singleton representing the team,

if existing. Otherwise None.
Return type:

helpscout.models.Person
classmethod get_members(session, team_or_id)[source]

List the members for the team.

Parameters:team_or_id (helpscout.models.Person or int) – Team or the ID of the team to get the folders for.
Returns:
Users
iterator.
Return type:RequestPaginator(output_type=helpscout.models.Users)
classmethod list(session)[source]

List the teams.

Parameters:session (requests.sessions.Session) – Authenticated session.
Returns:
Person
iterator representing the teams.
Return type:RequestPaginator(output_type=helpscout.models.Person)

helpscout.apis.users module

class helpscout.apis.users.Users[source]

Bases: helpscout.base_api.BaseApi

This represents the Users Endpoint.

The following aspects are implemented:

classmethod find_in_mailbox(session, mailbox_or_id)[source]

Get the users that are associated to a Mailbox.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • mailbox_or_id (MailboxRef or int) – Mailbox of the ID of the mailbox to get the folders for.
Returns:

Users

iterator.
Return type:

RequestPaginator(output_type=helpscout.models.User)
classmethod get_me(session)[source]

Return the current user.

Parameters:session (requests.sessions.Session) – Authenticated session.
Returns:A user singleton
Return type:helpscout.models.User

helpscout.apis.web_hook module

class helpscout.apis.web_hook.WebHook[source]

Bases: helpscout.base_api.BaseApi

This represents the WebHook Endpoint.

The following aspects are implemented:

classmethod create(session, web_hook)[source]

Create a web hook.

Note that creating a new web hook will overwrite the web hook that is already configured for this company. There is also no way to programmatically determine if a web hook already exists for the company. This is a limitation of the HelpScout API and cannot be circumvented.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • web_hook (helpscout.models.WebHook) – The web hook to be created.
Returns:

True if the creation was a success. Errors otherwise.
Return type:

bool

Module contents

class helpscout.apis.Conversations[source]

Bases: helpscout.base_api.BaseApi

This represents the Conversations Endpoint.

The following aspects are implemented:

classmethod create(session, record, imported=False, auto_reply=False)[source]

Create a conversation.

Please note that conversation cannot be created with more than 100 threads, if attempted the API will respond with HTTP 412.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • record (helpscout.models.Conversation) – The conversation to be created.
  • imported (bool, optional) – The imported request parameter enables conversations to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When imported is set to True, no outgoing emails or notifications will be generated.
  • auto_reply (bool) – The auto_reply request parameter enables auto replies to be sent when a conversation is created via the API. When auto_reply is set to True, an auto reply will be sent as long as there is at least one customer thread in the conversation.
Returns:

Newly created conversation.
Return type:

helpscout.models.Conversation
classmethod create_attachment(session, attachment)[source]

Create an attachment.

An attachment must be sent to the API before it can be used in a thread. Use this method to create the attachment, then use the resulting hash when creating a thread.

Note that HelpScout only supports attachments of 10MB or lower.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • attachment (helpscout.models.Attachment) – The attachment to be created.
Returns:

The newly created attachment (hash

property only). Use this hash when associating the attachment with a new thread.
Return type:

helpscout.models.Attachment
classmethod create_thread(session, conversation, thread, imported=False)[source]

Create a conversation thread.

Please note that threads cannot be added to conversations with 100 threads (or more), if attempted the API will respond with HTTP 412.

Parameters:
  • conversation (helpscout.models.Conversation) – The conversation that the thread is being added to.
  • session (requests.sessions.Session) – Authenticated session.
  • thread (helpscout.models.Thread) – The thread to be created.
  • imported (bool, optional) – The imported request parameter enables conversations to be created for historical purposes (i.e. if moving from a different platform, you can import your history). When imported is set to True, no outgoing emails or notifications will be generated.
Returns:

Conversation including newly created

thread.
Return type:

helpscout.models.Conversation
classmethod delete_attachment(session, attachment)[source]

Delete an attachment.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • attachment (helpscout.models.Attachment) – The attachment to be deleted.
Returns:

Nothing.
Return type:

NoneType
classmethod find_customer(session, mailbox, customer)[source]

Return conversations for a specific customer in a mailbox.

Parameters:
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod find_user(session, mailbox, user)[source]

Return conversations for a specific user in a mailbox.

Parameters:
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod get_attachment_data(session, attachment_id)[source]

Return a specific attachment’s data.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • attachment_id (int) – The ID of the attachment from which to get data.
Returns:

An attachment data singleton, if

existing. Otherwise None.
Return type:

helpscout.models.AttachmentData
classmethod list(session, mailbox)[source]

Return conversations in a mailbox.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • mailbox (helpscout.models.Mailbox) – Mailbox to list.
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod list_folder(session, mailbox, folder)[source]

Return conversations in a specific folder of a mailbox.

Parameters:
Returns:

Conversations iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Conversation)
classmethod search(session, queries)[source]

Search for a conversation given a domain.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • queries (helpscout.models.Domain or iter) – The queries for the domain. If a Domain object is provided, it will simply be returned. Otherwise, a Domain object will be generated from the complex queries. In this case, the queries should conform to the interface in helpscout.domain.Domain.from_tuple().
Returns:

SearchCustomer iterator.
Return type:

RequestPaginator(output_type=helpscout.models.SearchCustomer)
classmethod update_thread(session, conversation, thread)[source]

Update a thread.

Parameters:
Returns:

Conversation including freshly

updated thread.
Return type:

helpscout.models.Conversation
class helpscout.apis.Customers[source]

Bases: helpscout.base_api.BaseApi

This represents the Customers Endpoint.

The following aspects are implemented:

classmethod list(session, first_name=None, last_name=None, email=None, modified_since=None)[source]

List the customers.

Customers can be filtered on any combination of first name, last name, email, and modifiedSince.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • first_name (str, optional) – First name of customer.
  • last_name (str, optional) – Last name of customer.
  • email (str, optional) – Email address of customer.
  • modified_since (datetime.datetime, optional) – If modified after this date.
Returns:

Customers

iterator.
Return type:

RequestPaginator(output_type=helpscout.models.Customer)
classmethod search(session, queries)[source]

Search for a customer given a domain.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • queries (helpscout.models.Domain or iter) – The queries for the domain. If a Domain object is provided, it will simply be returned. Otherwise, a Domain object will be generated from the complex queries. In this case, the queries should conform to the interface in helpscout.domain.Domain.from_tuple().
Returns:

SearchCustomer iterator.
Return type:

RequestPaginator(output_type=helpscout.models.SearchCustomer)
class helpscout.apis.Mailboxes[source]

Bases: helpscout.base_api.BaseApi

This represents the Mailboxes Endpoint.

The following aspects are implemented:

classmethod get_folders(session, mailbox_or_id)[source]

List the folders for the mailbox.

Parameters:mailbox_or_id (helpscout.models.Mailbox or int) – Mailbox or the ID of the mailbox to get the folders for.
Returns:
Folders
iterator.
Return type:RequestPaginator(output_type=helpscout.models.Folder)
classmethod list(session)[source]

List the mailboxes.

Parameters:session (requests.sessions.Session) – Authenticated session.
Returns:
Mailboxes
iterator.
Return type:RequestPaginator(output_type=helpscout.models.Mailbox)
class helpscout.apis.Tags[source]

Bases: helpscout.base_api.BaseApi

This represents the Tags Endpoint.

The following aspects are implemented:

  • List Tags (helpscout.apis.tags.Tags.list())
class helpscout.apis.Teams[source]

Bases: helpscout.base_api.BaseApi

This represents the Teams Endpoint.

The following aspects are implemented:

classmethod get(session, team_id)[source]

Return a specific team.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • team_id (int) – The ID of the team to get.
Returns:

A person singleton representing the team,

if existing. Otherwise None.
Return type:

helpscout.models.Person
classmethod get_members(session, team_or_id)[source]

List the members for the team.

Parameters:team_or_id (helpscout.models.Person or int) – Team or the ID of the team to get the folders for.
Returns:
Users
iterator.
Return type:RequestPaginator(output_type=helpscout.models.Users)
classmethod list(session)[source]

List the teams.

Parameters:session (requests.sessions.Session) – Authenticated session.
Returns:
Person
iterator representing the teams.
Return type:RequestPaginator(output_type=helpscout.models.Person)
class helpscout.apis.Users[source]

Bases: helpscout.base_api.BaseApi

This represents the Users Endpoint.

The following aspects are implemented:

classmethod find_in_mailbox(session, mailbox_or_id)[source]

Get the users that are associated to a Mailbox.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • mailbox_or_id (MailboxRef or int) – Mailbox of the ID of the mailbox to get the folders for.
Returns:

Users

iterator.
Return type:

RequestPaginator(output_type=helpscout.models.User)
classmethod get_me(session)[source]

Return the current user.

Parameters:session (requests.sessions.Session) – Authenticated session.
Returns:A user singleton
Return type:helpscout.models.User
class helpscout.apis.WebHook[source]

Bases: helpscout.base_api.BaseApi

This represents the WebHook Endpoint.

The following aspects are implemented:

classmethod create(session, web_hook)[source]

Create a web hook.

Note that creating a new web hook will overwrite the web hook that is already configured for this company. There is also no way to programmatically determine if a web hook already exists for the company. This is a limitation of the HelpScout API and cannot be circumvented.

Parameters:
  • session (requests.sessions.Session) – Authenticated session.
  • web_hook (helpscout.models.WebHook) – The web hook to be created.
Returns:

True if the creation was a success. Errors otherwise.
Return type:

bool