HelpScout integration

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.

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

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

Conversation: Create

Parameter	Type	Required	Default	Description
Mailbox ID	string	Yes	—	The ID of the mailbox to fetch, or to create the conversation in; use Mailbox Get Many to find mailbox IDs.
Status	options	Yes	active	Conversation status.
				Options: active, closed, pending
Subject	string	Yes	—	Conversation subject line.
Type (conversationType)	options	Yes	email	Channel the conversation belongs to: chat, email, or phone.
				Options: chat, email, phone
Resolve Data	boolean	No	true	Whether to fetch the full created record; if false, only its ID and URI are returned.
Additional Fields	collection	No	{}
				Options: female
— 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	string	Yes	—	The ID of the conversation to act on.

Conversation: Get

Parameter	Type	Required	Default	Description
Conversation ID	string	Yes	—	The ID of the conversation to act on.

Conversation: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)
Options	collection	No	{}
				Options: threads, createdAt, asc, active, score
— 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	—
				Options: createdAt, customerEmail, customerName, mailboxid, modifiedAt, number, score, status, subject
— Sort Order	options	No	desc
				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	boolean	No	true	Whether to fetch the full created record; if false, only its ID and URI are returned.
Additional Fields	collection	No	{}
				Options: female
— Age	number	No	1	Customer age.
— First Name	string	No	—	First name (1-40 characters).
— Gender	options	No	—
				Options: female, male, unknown
— Job Title	string	No	—	Job title (max 60 characters).
— Last Name	string	No	—
— Location	string	No	—
— Notes	string	No	—
— Organization	string	No	—
— Photo URL	string	No	—
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	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)
Options	collection	No	{}
				Options: threads, createdAt, asc, active, score
— 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
				Options: score, firstName, lastName, modifiedAt
— Sort Order	options	No	desc
				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	{}
				Options: female
— Age	number	No	1
— First Name	string	No	—
— Gender	options	No	—
				Options: female, male, unknown
— Job Title	string	No	—
— Last Name	string	No	—
— Location	string	No	—
— Notes	string	No	—
— Organization	string	No	—
— Photo URL	string	No	—

Mailbox: Get

Parameter	Type	Required	Default	Description
Mailbox ID	string	Yes	—	The ID of the mailbox to fetch, or to create the conversation in; use Mailbox Get Many to find mailbox IDs.

Mailbox: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given 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	string	Yes	—	The ID of the conversation to act on.
Type (threadType)	options	Yes	note	Kind of thread to add to the conversation; this selects the endpoint, so a reply, customer message, note, chat, or phone thread.
				Options: chat, customer, note, phone, reply
Text	string	Yes	—	The message body text (HTML supported).
Additional Fields	collection	No	{}
				Options: female
— 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	string	Yes	—	The ID of the conversation to act on.
Return All	boolean	No	false	Whether to return all results or only up to a given 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.

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

This tool manages HelpScout conversations, customers, mailboxes, and threads. It is ideal for creating new conversations, updating customer information, or adding threads with file attachments, rather than managing other types of records. It produces updated HelpScout records, new conversations or threads, or lists of existing items.