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.

List Conversations

4 available variations:

  1. Return conversations in a mailbox
    • REST Method: GET
    • URL: https://api.helpscout.net/v1/mailboxes/{mailboxId}/conversations.json

  2. Return conversations in a specific folder of a mailbox
    • REST Method: GET
    • URL: https://api.helpscout.net/v1/mailboxes/{mailboxId}/folders/{folderId}/conversations.json

  3. Return conversations for a specific customer in a mailbox
    • REST Method: GET
    • URL: https://api.helpscout.net/v1/mailboxes/{mailboxId}/customers/{customerId}/conversations.json

  4. Return conversations assigned to a specific user in a mailbox
    • REST Method: GET
    • URL: https://api.helpscout.net/v1/mailboxes/{mailboxId}/users/{userId}/conversations.json

Currently all conversations are returned by createdAt date (from newest to oldest). Threads are never returned on the Conversation object when listing conversations. To get the conversation threads, you need to call the Get Conversation method.

Request

Name Type Required Default Options Notes
page Int No 1    
status String No all
  • all
  • active
  • pending
 Active/Pending only applies to the following folders:
  1. Unassigned
  2. Mine
  3. Drafts
  4. Assigned
modifiedSince Datetime No     Returns conversations that have been modified since the given date/time. Date/time is in UTC
tag String No     Returns conversations that have been tagged with any of the specified tags. More than one tag can be specified by separating the tags with a comma (no spaces).
  • tag=todo
  • tag=todo,feature-request,follow-up
It is not currently possible to filter for conversations with all the specified tags. For example, conversations tagged with 'foo' AND 'bar'. This feature will be added in a future release.

To request subsequent pages:
https://api.helpscout.net/v1/mailboxes/{mailboxId}/conversations.json?page=2

Response

Response Name Type Notes
Header Status Int 200
Body page Int Current page that was passed in on the request
  pages Int Total number of pages available
  count Int Total number of objects available
  items Collection Collection of Conversation objects. Conversation threads are not returned on this call. To get the conversation threads, you need to retrieve the full conversation object via the Get Conversation call. 
Status: 200 OK
{	
    "page": 1,
    "pages": 1,
    "count": 4,
    "items": [{
        "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",
        "userModifiedAt": "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"
        ],
        "threads": [{
            "id": 881881,
            "assignedTo": {
                "id": 1234,
                "firstName": "Jack",
                "lastName": "Sprout",
                "email": "jack.sprout@gmail.com",
                "phone": null,
                "type": "user"
            },
            "status": "active",
            "createdAt": "2012-07-23T12:34:12Z",
            "openedAt": "2012-07-23T3:21:43Z",
            "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"
            }]
        }],
        "bcc": [
            "bcc1@somewhere.com",
            "bcc2@somewhere.com"
        ],
        "tags": [
            "tag1",
            "tag2",
            "tag3"
        ]
    },
    {... conversation object ...},
    {... conversation object ...},
    {... conversation object ...}
    ]
}
↑Back to top
© Help Scout 2024