Changelog

2024-10-21 Added ‘conversationNumber’ rating property

This property carries the human-readable conversation number that’s presented to the user.

2024-08-27 Added ‘state’ attachment property

API responses with attachments now include information on the validity of the attachment and whether it might contain potentially malicious content. This update affects the following endpoints:

2024-06-13 Added ‘nextEvent’ conversation property

This property carries the “next event” that’s either a snooze or a thread schedule.

nextEvent property is available in the Conversation Response.

2024-06-13 Added ‘Schedule Thread’ API

This change adds a couple of new API operations for scheduling/unscheduling threads (called ‘Send Later’ in the web app).

The schedule data is optionally (if scheduled) available in the Thread Response

2024-05-31 Added ‘Snooze Conversation’ API

This change adds a pair of new API operations:

The snooze data is optionally (if snoozed) available in the Conversation Response.

2023-09-12 Added rating to thread response

API responses that include threads now contain rating information if available. This change impacts the following endpoints:

2023-08-30 Added Resource-ID response header to the thread creation endpoints

Added Resource-ID response header with an ID of the newly created thread to the following endpoints:

2023-07-04 Added Saved Replies update endpoint

Put Saved Reply updates a single saved reply

2023-04-05 Added Saved Replies crud endpoints

Get Saved Replies returns a list of saved replies for a given mailbox

Get Saved Reply returns a single saved reply

Post Saved Reply creates a new saved reply

Delete Saved Reply soft-deltes a saved reply

2022-10-20 Added GDPR delete endpoint

Delete Customer endpoint supports permanently removing customers. Currently there is a restriction that the customer must have 100 or fewer conversations.

2022-05-25 BREAKING Webhook payload version 1 deprecated

In May 2021, we released a new payload for our webhooks feature which offers improved compatibility with our current Mailbox API. As a result of this release, we announced the full sunset of the previous webhooks payload, referred to as V1 in your Help Scout account, in November 2021. We reached out to all integration partners with the V1 webhook payloads and worked with them on migrating to V2 payload.

As of today, it is no longer possible to create webhooks with V1 payload and V2 is now the default value if the payloadVersion field is omitted. Same restriction applies to Update Webhook where it’s not possible to set payload back to V1.

2020-10-05 Webhook Labels

Get/List/Create/Update Webhook now supports an optional label property. Omitting this property resuls in a Webhooks fallback value.

2020-08-11 Customer Properties

The API now supports Customer Properties for companies on our non-legacy Plus and Company plans. Check out these endpoints:

2020-08-11 New webhook payload version

Create Webhook now supports payloadVersion field that allows you to switch to webhook payloads modelled after Mailbox API 2.0.

2020-07-23 BUGFIX Status change when adding customer threads to conversations

The behaviour of some endpoints which add customer threads (customer, chat and phone thread types) was somewhat inconsistent. After this fix, when a new customer thread is added to a closed conversation, the conversation will be reopened unless the thread is imported (signalled by imported: true field value).

2020-05-20 Sort conversations by Waiting Since

List Conversations now supports sorting by waitingSince via ?sortField=waitingSince

2020-03-31 PATCH Customer is here

Update Customer now offers atomic updates of the whole Customer object including all customer entries (emails, phones, social profiles, chat handles and address) in one request.

2019-12-18 Get original thread source

There are two new endpoints to get original thread source - either as a JSON or even as a RFC 822 text.

Use ?embed=threads parameter to load all threads in List Conversations!

2019-10-04 Embedding threads in List Conversations

Use ?embed=threads parameter to load all threads in List Conversations!

2019-09-10 Additional user fields

We added jobTitle, phone and alternateEmails fields to List Users and Get User endpoints

2019-08-29 More information about user who closed a conversation

There is a new closedByUser object in List Conversations and Get Conversation which contains name and email of the user who closed the conversation

2019-07-31 Change conversation status when replying or adding a note

Create Reply and Add Note endpoints now support status field that allows you to change the conversation status when adding a thread.

2019-07-09 Empty results are now really empty results

Instead of returning {"_embedded" : {"results": []}} various List endpoints did not include the _embedded object at all which meant that clients had to check for existence of the field. We heard your complaints and made sure empty result list always means an empty array.

2019-06-11 Team endpoints are here

We added new List Teams and List Team Members endpoints

2019-05-16 Full customer details in the conversation object

The primaryCustomer object in List Conversations and Get Conversation endpoints now contains full customer details (it used to show just id)

2019-05-15 New Reports!

We added new Email Report, Phone Report, Chat Report and All Channels - Volumes by Channel

2019-03-20 Return dropdown option labels in conversations

List Conversations and Get Conversation got a new text field in the custom field object that contains the text value of custom fields. This is interesting especially for dropdown, because the value field only holds ID of the selected option but text hold the option label.

2019-02-08 BUGFIX Create Customer Thread was not re-opening conversations

Created Customer Thread was not re-opening conversations when a new thread was added. This is fixed now - the conversation will be re-opened unless imported field is set to true.

2019-02-01 New HTTP Status

The API now returns HTTP 504 status when an internal call times out indicating that said request can be retried safely.

2019-01-25 Return all customer entries, always

You asked, we delivered ���� Get Customer and List Customers endpoints now embed all customer entries, always. It means that the embed param in Get Customer is effectively deprecated.

You can now filter conversations by custom fields in List Conversations.

List endpoints like List Conversations return pagination links - for example link to next page (/v2/conversations?page=2). But in case the request contained query params (/v2/conversations?status=closed), these were not included in the links which was illogical and actually a bug.

We brought the parameters back and the next link would now properly say /v2/conversations?status=closed&page=2

2018-11-13 Workflows!

All the Workflow endpoints are here. You can list workflows, change their status and run manual workflows.

2018-09-26 Update thread text

And here’s Update Thread endpoint for you :-)

2018-09-25 Create customer entries

You can now add all customer entries (emails, phones, .. etc) in the Create Customer endpoint.

2018-09-25 Documentation updates

We looked at Create Conversation again and updated the documentation - state was marked as required and threads documentation was improved. List Webhooks is now visible and Create Webhook was corrected as well - it used to display text from the Update Webook endpoint before.

2018-09-14 Additional customer fields in Create Conversation

The Customer object in the Create Conversation endpoint supports additional fields like name, organization, etc.

2018-09-12 state param in Authorization Code Flow

You can now use the optional state parameter in the Authorization Code Flow

2018-09-05 Embed customer sub entities (emails, chats, …)

If you want to load a customer object with all entries like emails, chats and other, use the new embed param in Get Customer endpoint

2018-08-29 Add tags and custom fields when creating conversation

You can now add tags and custom fields directly in the Create Conversation endpoint.

2018-08-21 Draft reply

It is now possible to use draft field in both Create Conversation and Create Reply endpoints to create a draft instead of a reply.

2018-08-10 Embed Threads to Conversation

Get Conversation endpoints now support embed parameter that can pre-load threads when returning the conversation object

2018-07-30 Web Hooks overhaul

It is now possible to create multiple web hooks per account!

2018-07-17 Documentation update

There was an issue in the List Conversations documentation. Query operator mailboxName doesn’t exist, it’s actually called mailbox and it can be used in /v2/conversations?query=(mailbox: "Help Scout").

We also documented status param all that will give you all conversations no matter what their status is - /v2/conversations?status=all.

2018-05-15 Open for business

Mailbox API 2.0 is now available to all Help Scout users on paid plans.

2018-04-16 Transition service

Authors of Help Scout integrations can use our Transition service to exchange V1 API keys for OAuth2 tokens.

2018-04-11 Custom Fields in conversation object

Both Get Conversation and List Conversations responses now contain custom fields.

2018-04-10 - Web Hooks!

The API now supports Web Hook endpoints

2018-03-06 - Imported threads with createdAt

Imported threads now allow overriding of createdAt value.

2018-03-06 - Update conversation owner

Update Conversation is able assign and un-assign a conversation

2018-03-05 - Update conversation status

Update Conversation is able to update the conversation status now

2018-02-28 - Locked conversations

The API now returns nice error message when adding threads to conversation with 100 or more conversations.

2018-02-26 - Moved or merged conversations

The API now handles moved or merged conversations

2018-02-20 - Mailbox API 2.0 in Beta

Mailbox API 2.0 is now Beta. It covers almost all V1 resources with the exception of Webhooks and Workflows.

Dates are in YYYY-MM-DD format.

↑Back to top
© Help Scout 2024