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.

Search Conversations

  • REST Method: GET
  • URL: https://api.helpscout.net/v1/search/conversations.json

Search Reference

Operator Example What it does
Subject query=(subject:"rainbow") Searches for conversation subjects that contain the word "rainbow"
  query=(subject:"have a question") Searches for conversation subjects that contain the phrase "have a question" (not case sensitive)
  query=(subject:"coffee" OR subject:"tea") Searches for conversations with a subject that contain the word "coffee" or the word "tea"
  query=(subject:"coffee tea") Searches for conversation subjects that contain the word "coffee" and the word "tea" in no particular order
Tags query=(tag:"carrots") Searches for conversations that have the tag "carrots"
  query=(tag:"dogs love carrots") Searches for conversations that have the tag "dogs love carrots"
  query=(tag:"dogs" OR tag:"carrots") Searches for conversations that are tagged with either "dogs" or "carrots"
Mailbox query=(mailboxName:"Orders") Searches the "Orders" mailbox (case sensitive)
  query=(mailboxid:100) Searches the mailbox with an id of 100
Customer query=(customerIds:xxxxxxx) Returns conversations (across all mailboxes) belonging to the given customer
Number query=(number:1234) Searches for conversation #1234
Id query=(id:123456) Searches for the unique conversation ID (before the conversation number in the URL)
Assigned query=(assigned:"spock") Searches for conversations assigned to Spock
Attachment query=(attachment:true) Searches for conversations with attachments
Unassigned query=(assigned:"Unassigned") Searches for unassigned conversations
Body query=(body:"what a beautiful day") Searches conversation threads for the phrase, "what a beautiful day"
  query=(body:"what a day" OR body:"how about tomorrow") Searches conversation threads for the phrase, "what a day" or "how about tomorrow"
Status query=(status:active) Searches conversations that have a status of active. Active, Pending, Closed and Spam work here.
  query=(status:active OR status:pending) Searches conversations that have a status of active or pending
Modified At query=(modifiedAt:[2014-02-27T00:00:00Z TO *]) Searches conversations that have been modified since 2014-02-27
  query=(modifiedAt:[2014-02-27T00:00:00Z TO 2014-02-27T23:59:59Z]) Searches conversations that were modified on 2014-02-27
  query=(modifiedAt:[NOW-1HOUR]) Searches conversations that were modified in the last hour
  query=(modifiedAt:[2013-01-01T00:00:00Z/YEAR]) Searches conversations that were modified in 2013
Created At query=(createdAt:[2014-02-27T00:00:00Z TO *]) Searches conversations that have been created since 2014-02-27
  query=(createdAt:[2014-02-27T00:00:00Z TO 2014-02-27T23:59:59Z]) Searches conversations that were created on 2014-02-27
  query=(createdAt:[NOW-1HOUR]) Searches conversations that were created in the last hour
  query=(createdAt:[2013-01-01T00:00:00Z/YEAR]) Searches conversations that were created in 2013
Email query=(email:john@appleseed.com) Searches conversations where john@appleseed.com emails is either in to, cc, bcc fields or it's one of the emails in a customer profile.
  query=(email:(john@appleseed.com OR vbear@mywork.com)) Searches conversations using the fields mentioned above, but returns results for multiple emails or customers
Combined query=(assigned:"spock" AND status:active) Searches conversations that are assigned to Spock and have a status of active
  query=(mailbox:"Support" AND tag:"carrots") Searches conversations in the Support mailbox that have the tag "carrots"

Request

Name Type Required Default Options Notes
page Int No 1    
pageSize Int No 50 0-50 50 is the default and also the maximum page size
query String No *   If no query is specified, all conversations will be returned.
sortField String No score
  • customerEmail
  • customerName
  • mailboxid
  • modifiedAt
  • number
  • score
  • status
  • subject
 customerEmail sort option does not work at the moment
sortOrder String No desc
  • asc
  • desc
  

To request subsequent pages:
https://api.helpscout.net/v1/search/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 SearchConversation objects 
Status: 200 OK
{
    "page": 1,
    "pages": 1,
    "count": 4,
    "items": [
        {
            "id": 2391938111,
            "number": "349",
            "mailboxid": 1234,
            "subject": "I need help!",
            "status": "active",
            "threadCount": 3,
            "preview": "Hello, I tried to download the file off your site...",
            "customerName": "John Appleseed",
            "customerEmail": "john@appleseed.com",
            "modifiedAt": "2012-07-24T20:18:33Z"
        }
        {... search conversation object ...},
        {... search conversation object ...},
        {... search conversation object ...}
    ]
}
↑Back to top
© Help Scout 2024