HelpScout

Manage HelpScout conversations, customers, mailboxes, and threads

Overview

HelpScout integration for the Mailbox API v2. Supports CRUD operations on conversations (create, delete, get, getAll), customers (create, get, getAll, properties, update), mailboxes (get, getAll), and threads (create with file attachments, getAll). Thread creation supports binary attachments that are base64-encoded and sent to the HelpScout API. Uses OAuth2 client credentials authentication.

Category: Productivity
Tool Name: helpscout
Version: 1

Appearance: Icon: si-helpscout | Color: #1292EE

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires HelpScout OAuth2 credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Conversation	conversation
Customer	customer
Mailbox	mailbox
Thread	thread

Operations

Conversation (conversation)

Operation	Value	Description
Create	create	Create a new conversation
Delete	delete	Delete a conversation
Get	get	Get a conversation
Get Many	getAll	Get many conversations

Customer (customer)

Operation	Value	Description
Create	create	Create a new customer
Get	get	Get a customer
Get Many	getAll	Get many customers
Properties	properties	Get customer property definitions
Update	update	Update a customer

Mailbox (mailbox)

Operation	Value	Description
Get	get	Get a mailbox
Get Many	getAll	Get many mailboxes

Thread (thread)

Operation	Value	Description
Create	create	Create a new thread
Get Many	getAll	Get many threads

Parameters

Customer: Properties takes no parameters of its own — see All Operations.

String, number, JSON and collection fields are resolved per input item, so they accept {{ $json.field }} expressions.

Conversation: Create

Parameter	Type	Required	Default	Description
Mailbox ID (mailboxId)	string	Yes	—	ID of the mailbox where the conversation is being created. Use the Mailbox: Get Many operation to find mailbox IDs.
Status	options	Yes	active	Conversation status.
				Options: active, closed, pending
Subject	string	Yes	—	Conversation subject line.
Type (type)	options	Yes	email	Conversation type.
				Options: chat, email, phone
Resolve Data (resolveData)	boolean	No	true	Whether to fetch the full conversation after creation. If false, only the ID and URI are returned.
Additional Fields (additionalFields)	collection	No	{}	Optional fields to set on the new conversation. One of Customer Email or Customer ID must be set here, or the item fails.
— Assign To	number	No	0	User ID to assign the conversation to.
— Auto Reply	boolean	No	false	Whether to send an auto-reply if there is at least one customer thread.
— Closed At	string	No	—	ISO 8601 datetime when the conversation was closed (for imports).
— Created At	string	No	—	ISO 8601 datetime when the conversation was created.
— Customer Email	string	No	—	Customer email address. Either this or Customer ID is required.
— Customer ID	number	No	0	Customer ID. Either this or Customer Email is required.
— Imported	boolean	No	false	Whether to suppress outgoing emails and notifications.
— Tags	string	No	—	Comma-separated list of tag names to add to the conversation.
— User ID	number	No	0	ID of the user creating the conversation.
Threads	json	No	[]	JSON array of thread objects. Each thread: { “type”: “chat|customer|note|phone|reply”, “text”: “message body”, “bcc”: [], “cc”: [], “draft”: false }.

Conversation: Delete

Parameter	Type	Required	Default	Description
Conversation ID (conversationId)	string	Yes	—	The ID of the conversation.

Conversation: Get

Parameter	Type	Required	Default	Description
Conversation ID (conversationId)	string	Yes	—	The ID of the conversation.

Conversation: Get Many

Parameter	Type	Required	Default	Description
Return All (returnAll)	boolean	No	false	Whether to return all results or only up to a given limit.
Limit (limit)	number	No	50	Max number of results to return. (shown when Return All is false)
Options (options)	collection	No	{}	Filters and sorting for the conversation listing.
— Assign To	number	No	0	Filter by assignee user ID.
— Embed	options	No	—	Embed thread data in the response.
				Options: threads
— Folder ID	string	No	—	Filter by folder ID.
— Mailbox ID	string	No	—	Filter by mailbox ID.
— Modified Since	string	No	—	ISO 8601 datetime. Returns only conversations modified after this date.
— Number	number	No	0	Look up by conversation number.
— Query	string	No	—	Advanced search query string.
— Sort Field	options	No	—	Field the results are sorted on.
				Options: createdAt, customerEmail, customerName, mailboxid, modifiedAt, number, score, status, subject
— Sort Order	options	No	desc	Sort direction.
				Options: asc, desc
— Status	options	No	active	Filter conversations by status.
				Options: active, all, closed, open, pending, spam
— Tags	string	No	—	Comma-separated tag names to filter by.

Customer: Create

Parameter	Type	Required	Default	Description
Resolve Data (resolveData)	boolean	No	true	Whether to fetch the full customer record after creation.
Additional Fields (additionalFields)	collection	No	{}	Customer fields to set. At least one field across this collection and the JSON fields below must be set, or the item fails.
— Age	number	No	1	Customer age.
— First Name	string	No	—	First name (1-40 characters).
— Gender	options	No	—	Customer gender.
				Options: female, male, unknown
— Job Title	string	No	—	Job title (max 60 characters).
— Last Name	string	No	—	Customer last name.
— Location	string	No	—	Customer location.
— Notes	string	No	—	Background notes about the customer.
— Organization	string	No	—	Company or organization the customer belongs to.
— Photo URL	string	No	—	URL of the customer’s photo.
Address	json	No	{}	JSON object: { “line1”: "", “line2”: "", “city”: "", “state”: "", “country”: “US”, “postalCode”: "" }.
Emails	json	No	[]	JSON array: [{ “type”: “work|home|other”, “value”: “email@example.com” }].
Phones	json	No	[]	JSON array: [{ “type”: “work|home|fax|pager|other”, “value”: “+1234567890” }].
Chat Handles	json	No	[]	JSON array: [{ “type”: “aim|gtalk|icq|msn|other|qq|skype|xmpp|yahoo”, “value”: “handle” }].
Social Profiles	json	No	[]	JSON array: [{ “type”: “facebook|twitter|linkedin|…”, “value”: “url_or_handle” }].
Websites	json	No	[]	JSON array: [{ “value”: “https://example.com” }].

Customer: Get

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	The ID of the customer.

Customer: Get Many

Parameter	Type	Required	Default	Description
Return All (returnAll)	boolean	No	false	Whether to return all results or only up to a given limit.
Limit (limit)	number	No	50	Max number of results to return. (shown when Return All is false)
Options (options)	collection	No	{}	Filters and sorting for the customer listing.
— First Name	string	No	—	Filter by first name.
— Last Name	string	No	—	Filter by last name.
— Mailbox ID	string	No	—	Filter by mailbox ID.
— Modified Since	string	No	—	ISO 8601 datetime filter.
— Sort Field	options	No	score	Field the results are sorted on.
				Options: score, firstName, lastName, modifiedAt
— Sort Order	options	No	desc	Sort direction.
				Options: asc, desc
— Query	string	No	—	Advanced search query.

Customer: Update

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	The ID of the customer.
Update Fields	collection	No	{}	Fields to change on the customer — set at least one, otherwise the item fails.
— Age	number	No	1	Customer age.
— First Name	string	No	—	Customer first name.
— Gender	options	No	—	Customer gender.
				Options: female, male, unknown
— Job Title	string	No	—	Customer job title.
— Last Name	string	No	—	Customer last name.
— Location	string	No	—	Customer location.
— Notes	string	No	—	Background notes about the customer.
— Organization	string	No	—	Company or organization the customer belongs to.
— Photo URL	string	No	—	URL of the customer’s photo.

Mailbox: Get

Parameter	Type	Required	Default	Description
Mailbox ID (mailboxId)	string	Yes	—	The ID of the mailbox.

Mailbox: Get Many

Parameter	Type	Required	Default	Description
Return All (returnAll)	boolean	No	false	Whether to return all results or only up to a given limit.
Limit (limit)	number	No	50	Max number of results to return. (shown when Return All is false)

Thread: Create

Parameter	Type	Required	Default	Description
Conversation ID (conversationId)	string	Yes	—	The ID of the conversation to add the thread to.
Type (type)	options	Yes	note	The type of thread to create.
				Options: chat, customer, note, phone, reply
Text	string	Yes	—	The message body text (HTML supported).
Additional Fields (additionalFields)	collection	No	{}	Optional fields to set on the new thread. One of Customer Email or Customer ID must be set here, or the item fails.
— Created At	string	No	—	ISO 8601 datetime for thread creation time.
— Customer Email	string	No	—	Customer email. Either this or Customer ID is required.
— Customer ID	number	No	0	Customer ID. Either this or Customer Email is required.
— Draft	boolean	No	false	Whether to create as a draft (note type only).
— Imported	boolean	No	false	Whether to suppress outgoing emails and notifications.
Manual Attachments	json	No	[]	JSON array of manual attachments: [{ “fileName”: “file.pdf”, “mimeType”: “application/pdf”, “data”: “base64string” }].
Binary Attachment Properties	string	No	—	Comma-separated binary property names to attach (e.g. “data,attachment_0”). Each binary property will be base64-encoded and sent as an attachment.

Thread: Get Many

Parameter	Type	Required	Default	Description
Conversation ID (conversationId)	string	Yes	—	The ID of the conversation to get threads for.
Return All (returnAll)	boolean	No	false	Whether to return all results or only up to a given limit.
Limit (limit)	number	No	50	Max number of results to return. (shown when Return All is false)

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

Exactly one output item per input item — this node never fans out, not even on the Get Many operations. Binary data on the input item is forwarded unchanged; attachments you send with a thread are uploaded to HelpScout and are not returned as binary.

How the response reaches the item depends on its shape:

• Listings are nested, not merged. When HelpScout returns an array, the records are written to results on the output item and their number to resultCount. The rest of the item JSON passes through untouched. An empty listing still produces one item, with results: [] and resultCount: 0.
• Single records are merged at the top level. When HelpScout returns one object, its fields are spread onto the item JSON, so response fields can overwrite incoming fields of the same name.
• Operations with no response body set success: true on the item, leaving the rest of the item JSON in place.

Operation	What lands on the output item
Conversation: Create	The full conversation record merged at the top level when Resolve Data is on; with it off, only id and uri
Conversation: Delete	success: true
Conversation: Get	The conversation record merged at the top level
Conversation: Get Many	results (conversations) and resultCount
Customer: Create	The full customer record merged at the top level when Resolve Data is on; with it off, only id and uri
Customer: Get	The customer record merged at the top level
Customer: Get Many	results (customers) and resultCount
Customer: Properties	results (property definitions) and resultCount
Customer: Update	success: true
Mailbox: Get	The mailbox record merged at the top level
Mailbox: Get Many	results (mailboxes) and resultCount
Thread: Create	success: true
Thread: Get Many	results (threads) and resultCount

Reference the result downstream by expression — {{ $json.resultCount }} for a listing, {{ $json.id }} for a create with Resolve Data off. Because listings arrive as one item holding an array, use a Split Out node on results when you need one workflow item per record.

Usage Examples

• Create a new conversation in HelpScout
• List all customers
• Add a thread with file attachment to a conversation
• Get conversation details by ID
• Update customer information

Example Configuration

Create a new conversation:

{
  "type": "helpscout",
  "parameters": {
    "resource": "conversation",
    "operation": "create",
    "mailboxId": "12345",
    "subject": "Customer Support Request",
    "type": "email",
    "status": "active",
    "resolveData": true,
    "additionalFields": {
      "customerEmail": "customer@example.com",
      "tags": "urgent,billing",
      "assignTo": 67890
    },
    "threads": [
      {
        "type": "customer",
        "text": "I need help with my billing inquiry.",
        "draft": false
      }
    ]
  }
}

Get all conversations with filters:

{
  "type": "helpscout",
  "parameters": {
    "resource": "conversation",
    "operation": "getAll",
    "returnAll": false,
    "limit": 50,
    "options": {
      "status": "active",
      "mailbox": "12345",
      "sortField": "createdAt",
      "sortOrder": "desc",
      "query": "billing"
    }
  }
}

Create a new customer:

{
  "type": "helpscout",
  "parameters": {
    "resource": "customer",
    "operation": "create",
    "resolveData": true,
    "additionalFields": {
      "firstName": "John",
      "lastName": "Doe",
      "organization": "Acme Corp",
      "jobTitle": "Manager"
    },
    "emails": [
      {
        "type": "work",
        "value": "john.doe@acme.com"
      }
    ],
    "phones": [
      {
        "type": "work",
        "value": "+1-555-123-4567"
      }
    ],
    "address": {
      "line1": "123 Business St",
      "city": "Business City",
      "state": "BC",
      "country": "US",
      "postalCode": "12345"
    }
  }
}

Update a customer:

{
  "type": "helpscout",
  "parameters": {
    "resource": "customer",
    "operation": "update",
    "customerId": "98765",
    "updateFields": {
      "jobTitle": "Senior Manager",
      "organization": "Acme Corporation",
      "location": "New York, NY"
    }
  }
}

Create a thread with attachments:

{
  "type": "helpscout",
  "parameters": {
    "resource": "thread",
    "operation": "create",
    "conversationId": "54321",
    "type": "reply",
    "text": "Thank you for contacting us. Please find the requested document attached.",
    "additionalFields": {
      "draft": false,
      "customerEmail": "customer@example.com"
    },
    "attachmentsManual": [
      {
        "fileName": "invoice.pdf",
        "mimeType": "application/pdf",
        "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..."
      }
    ]
  }
}

Get all customers with a search query:

{
  "type": "helpscout",
  "parameters": {
    "resource": "customer",
    "operation": "getAll",
    "returnAll": false,
    "limit": 25,
    "options": {
      "query": "john",
      "sortField": "score",
      "sortOrder": "desc",
      "modifiedSince": "2024-01-01T00:00:00Z"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Manage HelpScout conversations, customers, mailboxes, and threads with file attachment support via the Mailbox API v2.