Legacy Mailbox API 1.0 is deprecated

Legacy Mailbox API 1.0 was deprecated on November 20, 2019. Please use Mailbox API 2.0 going forward. If you have any questions or need help with the new API, please reach out.

Conversation Object

Field Guide

The following fields are returned when listing conversations.

Name Type Example Notes
id Int 291938 Unique identifier
type String email The type of conversation.
  • email
  • chat
  • phone
folderId Int 1234 ID of the Mailbox Folder to which this conversation resides.
isDraft Boolean false  
number Int 349 The conversation number displayed in the UI. This number can be used in combination with the id to construct a URL to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/
owner Person   The Help Scout user who is currently assigned to this conversation.
mailbox MailboxRef   MailboxRef to which this conversation belongs.
customer Person   The customer who this conversation is associated with.
threadCount Int 4 This count represents the number of published threads found on the conversation (it does not include line items, drafts or threads held for review by Collision Detection).
status String active Status of the conversation. Possible values include:
  • active
  • pending
  • closed
  • spam
subject String I need help!  
preview String Hello, I tried to download the file off your site...  
createdBy Person   The Person who created this conversation. The 'type' property will specify whether it was created by a 'user' or a 'customer'.
createdAt Datetime 2012-07-23T12:34:12Z UTC time when this conversation was created.
modifiedAt or userModifiedAt Datetime 2012-07-24T20:18:33Z UTC time when a user last modified this conversation.
closedAt Datetime   UTC time when this conversation was closed. Null if not closed
closedBy Person   The Help Scout user who closed this conversation.
source Source   Specifies the method in which this conversation was created.
cc Collection   Collection of strings representing email addresses
bcc Collection   Collection of strings representing email addresses
tags Collection   Collection of strings

Additional Fields

In addition to the fields above, the following fields are returned when retrieving a single Conversation.

Name Type Example Notes
threads Collection   Collection of Thread objects
customFields Collection   Collection of Field objects; only included for Plus Plan accounts

Example

{
  "id": 291938,
  "type": "email",
  "folderId": "1234",
  "isDraft": "false",
  "number": 349,
  "owner": {
    "id": 1234,
    "firstName": "Jack",
    "lastName": "Sprout",
    "email": "jack.sprout@gmail.com",
    "phone": null,
    "type": "user"
  },
  "mailbox": {
    "id": 1234,
    "name": "My Mailbox"
  },
  "customer": {
    "id": 29418,
    "firstName": "Vernon",
    "lastName": "Bear",
    "email": "vbear@mywork.com",
    "phone": "800-555-1212",
    "type": "customer"
  },
  "threadCount": 4,
  "status": "active",
  "subject": "I need help!",
  "preview": "Hello, I tried to download the file off your site...",
  "createdBy": {
    "id": 29418,
    "firstName": "Vernon",
    "lastName": "Bear",
    "email": "vbear@mywork.com",
    "phone": null,
    "type": "customer"
  },
  "createdAt": "2012-07-23T12:34:12Z",
  "modifiedAt": "2012-07-24T20:18:33Z",
  "closedAt": null,
  "closedBy": null,
  "source": {
    "type": "email",
    "via": "customer"
  },
  "cc": [
    "cc1@somewhere.com",
    "cc2@somewhere.com"
  ],
  "bcc": [
    "bcc1@somewhere.com",
    "bcc2@somewhere.com"
  ],
  "tags": [
    "tag1",
    "tag2"
  ],
  "customFields": [
    {
      "fieldId": 1,
      "name": "Team",
      "value": "Development"
    },
    {
      "fieldId": 2,
      "name": "Customer Disposition",
      "value": "Happy"
    }
  ],
  "threads": [
    {
      "id": 88171881,
      "assignedTo": {
        "id": 1234,
        "firstName": "Jack",
        "lastName": "Sprout",
        "email": "jack.sprout@gmail.com",
        "phone": null,
        "type": "user"
      },
      "status": "active",
      "createdAt": "2012-07-23T12:34:12Z",
      "createdBy": {
        "id": 1234,
        "firstName": "Jack",
        "lastName": "Sprout",
        "email": "jack.sprout@gmail.com",
        "phone": null,
        "type": "user"
      },
      "source": {
        "type": "web",
        "via": "user"
      },
      "type": "message",
      "state": "published",
      "customer": {
        "id": 29418,
        "firstName": "Vernon",
        "lastName": "Bear",
        "email": "vbear@mywork.com",
        "phone": "800-555-1212",
        "type": "customer"
      },
      "fromMailbox": null,
      "body": "This is what I have to say. Thank you.",
      "to": [
        "customer@somewhere.com"
      ],
      "cc": [
        "cc1@somewhere.com",
        "cc2@somewhere.com"
      ],
      "bcc": [
        "bcc1@somewhere.com",
        "bcc2@somewhere.com"
      ],
      "attachments": [
        {
          "id": 12391,
          "mimeType": "image/jpeg",
          "filename": "logo.jpg",
          "size": 22,
          "width": 160,
          "height": 160,
          "url": "https://secure.helpscout.net/some-url/logo.jpg"
        }
      ],
      "tags": [
        "tag1",
        "tag2",
        "tag3"
      ]
    }
  ]
}
↑Back to top
© Help Scout 2024