npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

node-helpscout

v2.0.1

Published

Simple wrapper class to access HelpScout's Mailbox API 2.0; handles Client Credentials Flow authentication

Downloads

227

Readme

Help Scout Mailbox API 2.0 Client - Node.js

publish node package to npm

About this Module

This module was built to make using Help Scout's Inbox API 2.0 endpoints as easy as possible.

It contains wrappers around each type of endpoint (Create, List, Update, etc.) to manage the authentication, error handling, and other stuff you probably don't want to spend a lot of time coding for.

This module supports the Client Credentials Flow authentication method which is suited for apps you can create and manage, ideally suited for internal projects.

Disclaimer: This module is not in any way affiliated to or supported by Help Scout Inc. It's an open-source act of love to get to the fun part of writing code faster.

Installation

$ npm install node-helpscout

Initialization

Create an OAuth2 Application First things first, create an OAuth2 Application under your profile in Help Scout. We won't be using the OAuth flow so the redirect URL is not needed to use this module.

Import the Module and Create a Client All API Methods are made available via a Help Scout Client. Once you create your OAuth2 application, we'll use the App Id and Secret provided to authenticate your API Calls.

It may look something like this when you're done:

const NodeHelpScout = require("node-helpscout");

const HelpScoutClient = new NodeHelpScout({
    clientId: process.env.HELPSCOUT_CLIENT_ID,
    clientSecret: process.env.HELPSCOUT_APP_SECRET,
});

🎉 Awesome! You now have a client that can use all of the helper methods below.

Testing

A full test suite is available for your convenience.

Step 1: Create a file called .env in the root directory of this project and add add HELPSCOUT_CLIENT_ID and HELPSCOUT_CLIENT_SECRET to provide your Client Id and Secret obtained above.

Step 2: Run the tests

$ npm test

The output should look something like this:

all tests passing

Features

This library returns promises to allow use of async/await. TypeScript type definitions are provided for all the methods.

HTTP Methods

create();

Create a new Resource.

await HelpScoutClient.create(resource, data, parentResource, parentResourceId);

resource: Type of Resource to create ("conversations", "customers", ..)

data: Object containing the resource data

parentResource: Optional field to support resources that are created below an existing resource.

parentResourceId: Optional field indicating Id the parent resource that this resource should be created under.

Example: Create a new Customer

const customer = {
    firstName: "John",
    lastName: "Doe",
    emails: [{ type: "work", value: "[email protected]" }],
};

const customerId = await HelpScoutClient.create("customers", customer);

Example2: Create a new note in a conversation

const conversationId = 123456789;
await HelpScoutClient.create(
    "notes",
    { text: "An example note." },
    "conversations",
    conversationId
);

Note: No id is passed from Help Scout when creating child objects like notes.

list();

Get a list of Resources, this module handles the pagination and rate-limiting for you. If no results are returned, an empty array is returned.

const resourceArray = await HelpScoutClient.list(
    resource,
    queryParams,
    parentResource,
    parentResourceId
);

resource: Type of Resource to list ("conversations", "customers", ..)

queryParams: Query String to use - Help Scout supports a ton of super cool, super complex query strings like this or this. This parameter expects a string to put after the "?" in the request, do not include the "?" mark in the string you pass in.

parentResource: Optional field to support resources that are created below an existing resource.

parentResourceId: Optional field indicating Id the parent resource that this resource should be created under.

Example: Get all Mailboxes

const mailboxArray = await HelpScoutClient.list("mailboxes");

Example: Get all Customers

const customersArray = await HelpScoutClient.list("customers", null, "", "");

get();

Get a specific resource based on an id

const resource = await HelpScoutClient.get(
    type,
    resourceId,
    embeddables,
    subType
);

resource: Type of Resource to get ("conversations", "customers", ..)

resourceId: Id of the resource you'd like to retrieve.

embeddables: On certain endpoints like Customers, Help Scout requires you explicitly ask for any lists of related resources. Pass in an array of related resource labels (as strings) to have those included in the object that comes back, see Example 1 below.

subType: Optional field for certain endpoints to return an array of Resources below the Resource you're getting, see Example 2 below.

Example 1: Get Customers with Emails and Social Profiles

const customer = await HelpScoutClient.get(
    "customers",
    123456789,
    ["emails", "social_profiles"],
    ""
);

Example 2: Get Folders in a Mailbox

const foldersArr = await HelpScoutClient.get(
    "mailboxes",
    166129,
    "",
    "folders"
);

updatePut();

For certain Help Scout Endpoints, you'll want to use the "PUT" method when updating a Resource. The PUT method replaces all of the Resource's properties with the data you specify.

await HelpScoutClient.updatePut(
    resource,
    resourceId,
    data,
    parentResource,
    parentResourceId
);

resource: Type of Resource to update ("conversations", "customers", ..)

resourceId: Optional, Id of the resource you'd like to update. (i.e. Email Address for Customer)

data: Object containing the resource data that will replace the current data

parentResource: Optional field to support resources that are updated below an existing resource.

parentResourceId: Optional field indicating Id the parent resource that this resource should be updated under.

Example: Update Email Address for a Customer

await HelpScoutClient.updatePut(
    "emails",
    123456789,
    {
        type: "work",
        value: "[email protected]",
    },
    "customers",
    987654321
);

updatePatch();

For certain Help Scout Endpoints, you'll want to use the "PATCH" method when updating a Resource. The PATCH method updates specific Resource properties while leaving other properties untouched. I highly recommend reviewing HelpScout's documentation of patching.

await HelpScoutClient.updatePut(
    resource,
    resourceId,
    data,
    parentResource,
    parentResourceId
);

resource: Type of Resource to update ("conversations", "customers", ..)

resourceId: Id of the resource you'd like to update.

data: Object containing the resource data that will replace the current data

parentResource: Optional field to support resources that are updated below an existing resource.

parentResourceId: Optional field indicating Id the parent resource that this resource should be updated under.

Example: Update Conversation Subject Line

await HelpScoutClient.updatePatch(
    "conversations",
    712477488,
    {
        op: "replace",
        path: "/subject",
        value: "Super cool new subject",
    },
    "",
    ""
);

Business Helpers

Some common operations require a couple of steps. The following methods simplify these operations with a simple call. For example, adding a note to a conversation. Try this:

For example, adding a note to a conversation. I feel it's a better experience to support something like:

await HelpScoutClient.addNoteToConversation(convoId, "Test Note");

as opposed to

await HelpScoutClient.create(
    "notes",
    { text: "Test Note" },
    "conversations",
    convoId
);

Public Base Methods

authenticate();

Note: This should never need to be called by your code directly, but it's provided if you ever need the access tokens for testing or debugging.

HelpScoutClient.authenticate();

The apiTokens property object has the following properties:

HelpScoutClient.apiTokens: {
    accessToken: string
    refreshToken: string
    expiresAt: number
}

"expiresAt" is the epoch expiration time calculated to make comparing to Date.now().

sendApiRequest();

If you want to leverage the authentication that comes with the client, but need to query something super specific or not covered by this module, this method is for you.

HelpScoutClient.sendApiRequest(method, url, data);

method: HTTP Method (GET, POST, DELETE, etc.)

url: Full URL, including everything from https:// to the query string.

data: For POST/PATCH/PUT requests, specify the data we should post to the URL

Help Wanted

This was put together as a project to help developers get developing quickly on the Help Scout platform. If you have an idea about how to extend this, want to contribute, or notice any issues, please file an Issue on Github.

License

This module is provided as an open-source project under the MIT License, it is not in any way supported or affiliated with Help Scout Inc.