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.

Received Messages

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

The received messages report provides a summary of he volume of received messages over a given time range. Only messages from customers are counted.

URL Parameters

A variety of filters are available as query parameters. Including any of these will result in only messages 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 Received Messages Statistics Contains he volume of received messages statistics for each day/hour of the week for the current time range
  previous Collection of Received Messages Statistics Contains he volume of received messages 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
    }
  ]
}