We're upgrading our API

On June 6th, 2019, Mailbox API 1.0 will be sunsetted, and at that time any apps using this legacy API will no longer work. Please use Mailbox API 2.0 instead.

New Conversations

  • REST Method: GET
  • URLs: https://api.helpscout.net/v1/reports/conversations/new.json

The new conversations report provides a summary of new conversation volume over a given time range.

URL Parameters

A variety of filters are available as query parameters. Including any of these will result in only new conversations that match the filters being included in the report.

Parameter Type Required Example
start Date/Time (ISO 8601, in UTC) Yes 2015-01-01T00:00:00Z
end Date/Time (ISO 8601, in UTC) Yes 2015-01-31T23:59:59Z
previousStart Date/Time (ISO 8601, in UTC) No 2014-01-01T00:00:00Z
previousEnd Date/Time (ISO 8601, in UTC) No 2014-01-31T23:59:59Z
mailboxes list of mailbox identifiers No 1,2,3
tags list of tag identifiers No 1,2,3
types list of conversation types (email, chat, or phone) No email,chat
folders list of folder identifiers No 1,2,3
viewBy resolution at which data is returned No week

Response

Response Name Type Notes
Header Status Int 200
Body current Collection of New Conversation Statistics Contains conversation volume statistics for each day/hour of the week for the current time range
  previous Collection of New Conversation Statistics Contains conversation volume statistics for each day/hour of the week for the previous time range; only included if a previous time range was specified

Example Response

{
  "current": [
    {
      "start": "2015-01-01T00:00:00Z",
      "count": 29
    },
    {
      "start": "2015-01-08T00:00:00Z",
      "count": 28
    },
    {
      "start": "2015-01-15T00:00:00Z",
      "count": 24
    },
    {
      "start": "2015-01-22T00:00:00Z",
      "count": 14
    },
    {
      "start": "2015-01-29T00:00:00Z",
      "count": 9
    }
  ],
  "previous": [
    {
      "start": "2014-01-01T00:00:00Z",
      "count": 3
    },
    {
      "start": "2014-01-08T00:00:00Z",
      "count": 15
    },
    {
      "start": "2014-01-15T00:00:00Z",
      "count": 577
    },
    {
      "start": "2014-01-22T00:00:00Z",
      "count": 9
    },
    {
      "start": "2014-01-29T00:00:00Z",
      "count": 20
    }
  ]
}