Search
Search for conversations
The Search Conversations endpoint allows you to search for conversations in team and private inboxes using the Core API.
https://api2.frontapp.com/conversations/search/lost shipmenthttps://api2.frontapp.com/conversations/search/lost%20shipmenthttps://api2.frontapp.com/conversations/search/is:archived is:unassignedhttps://api2.frontapp.com/conversations/search/is%3Aarchived%20is%3AunassignedAccess
The search results are limited to the scope of the API token.
For example, an API token with a Shared Resources scope has access to all team inboxes . An API token with a scope limited to a specific team can only search for conversations in that team inbox. An API with a scope set to Private Resources can access personal inboxes, assuming the individual teammates or an admin have allowed API access to personal data in the settings.
Search results
The API returns conversations that match the search query ordered by last activity date. There is no way to change the sort order at the moment. The API also returns the _total number of results and adheres to the Core API pagination pattern.
Basic Query Syntax
To search for conversations, pass a URL encoded query to the Search Conversations endpoint.
https://api2.frontapp.com/conversations/search/{query}
The query is made up of search text (that searches the subject and body) and filters such as tags or recipients, separated by spaces. The syntax for the query is as follows:
<text> <filter_name>:<filter_value>
Example: Search for “feedback”
feedbackfeedbackExample: Search for “feedback” and “urgent”
Separate multiple words with a space. The API only returns results that include all the words searched for.
feedback urgentfeedback%20urgentExample: Search for phrases
Enclose phrases in quotations. The following example returns conversations that include the exact phrase “urgent feedback” in the subject or body.
"urgent feedback"%22urgent%20feedback%22Example: Search for conversations sent to the email address “example@example.com”
to:example@example.comto%3Aexample%40example.comTip
You can search across multiple filters simultaneously.
Example: Search for conversations sent to the email address “example@example.com” that contain the word “conference” in the subject or body
conference to:example@example.comconference%20to%3Aexample%40example.comTip
You can search across multiple filters simultaneously.
Supported search filters
The following table lists the search filters that the Core API supports.
Filter name | Description | Example query (unencoded) |
|---|---|---|
inbox | Searches for conversations with a matching inbox ID. Note that the inbox ID is not the same as the name of the inbox. To obtain an inbox ID, use the List Inboxes endpoint. | inbox:inb_41w25 Lists conversations from the inbox with ID inb_41w25 |
tag | Searches for conversations with a matching tag ID. Note that the tag ID is not the same as the name of the tag. To obtain a tag ID, use the List tags endpoint. | tag:tag_13o8r1 Lists conversations tagged with a tag that has the ID tag_13o8r1 |
link | Searches for conversations that contain a link with a matching link ID. Note that the link ID is not the same as the name of the link. To obtain a link ID, use the List Links endpoint. | link:top_46ljh Lists conversations that contain a link with ID top_46ljh |
contact | Searches for conversations that contain a given contact ID in the recipient list, including when the contact is the sender. The contact can be in the from, to,cc, or bcc fields of any message in the conversation. Note that the Contact ID is not the same as the contact name. To obtain a contact ID, use the List Contacts endpoint. | contact:crd_1y8sp71 Lists conversations in which a recipient has the contact ID crd_1y8sp71 |
recipient | Searches for conversations that contain a given contact handle in the recipient list, including when the contact is the sender. The handle can be in the from,to, cc, or bccfields of any message in the conversation. Use the Get Contact endpoint to obtain a contact’s handles. Common handles include email address, social media handles, or Front chat ID. | recipient:dale.cooper@frontapp.com Lists conversations in which a recipient has the email address dale.cooper@frontapp.com |
from | Searches for conversations that were sent by a given contact handle. The handle must be in the from field of any message in the conversation. Use the Get Contact endpoint to obtain a contact’s handles. Common handles include email address, social media handles, or Front chat ID. | Lists conversations sent from the email address dale.cooper@frontapp.com |
to | Searches for conversations that were sent to a given contact handle. The handle can be in the to, cc, or bcc fields of any message in the conversation. Use the Get Contact endpoint to obtain a contact’s handles. Common handles include email address, social media handles, or Front chat ID. | Lists conversations sent to the email address dale.cooper@frontapp.com |
cc | Searches for conversations that were CC’ed to a given contact handle. The handle must be in the cc field of any message in the conversation. Use the Get Contact endpoint to obtain a contact’s handles. Common handles include email address, social media handles, or Front chat ID. | Lists conversations CC’ed to the email address dale.cooper@frontapp.com |
bcc | Searches for conversations that were BCC’ed to a given contact handle. The handle must be in the bcc field of any message in the conversation. Use the Get Contact endpoint to obtain a contact’s handles. Common handles include email address, social media handles, or Front chat ID. | Lists conversations BCC’ed to the email address dale.cooper@frontapp.com |
participant | Searches for conversations in which a given teammate ID is a participant. A participant is any teammate that comments, is assigned to, authors, is mentioned, or subscribes to a conversation. Use the List Teammates endpoint to obtain a teammate ID. | participant:tea_2thf Lists conversations in which the teammate with ID tea_2thf participated. |
assignee | Searches for conversations in which a given teammate ID is the assignee. Use the List Teammates endpoint to obtain a teammate ID. | assignee:tea_2thf Lists conversations in which the teammate with ID tea_2thf is the assignee. |
author | Searches for conversations in which a given teammate ID is the author. Use the List Teammates endpoint to obtain a teammate ID. | author:tea_2thf Lists conversations in which the teammate with ID tea_2thf is the author. |
mention | Searches for conversations in which a given teammate ID is mentioned. Use the List Teammates endpoint to obtain a teammate ID. | mention:tea_2thf Lists conversations in which the teammate with ID tea_2thf is mentioned. |
commenter | Searches for conversations in which a given teammate ID has commented. Use the List Teammates endpoint to obtain a teammate ID. | commenter:tea_2thf Lists conversations in which the teammate with ID tea_2thf is a commenter. |
is | Searches for conversations with a given status. The status options are:
Learn more about these statuses here. | is:snoozed Lists conversations that have been snoozed. |
before | Searches for conversations that contain messages or comments created before the minute specified by the Unix timestamp. The filter applies to all messages and comments in the conversation. It is not limited to the initial message or comment in the conversation, so it should not be interpreted as a means to filter for conversations created before a certain date. | before:1649974320 List conversations that contain messages or comments created before |
after | Searches for conversations that contain messages or comments created after the minute specified by the Unix timestamp. The filter applies to all messages and comments in the conversation. It is not limited to the initial message or comment in the conversation, so it should not be interpreted as a means to filter for conversations created after a certain date. | after:1649974320 List conversations that contain messages or comments created after |
during | Searches for conversations with messages or comments created on the same day of the specified Unix timestamp. The filter applies to all messages and comments in the conversation. It is not limited to the initial message or comment in the conversation, so it should not be interpreted as a means to filter for conversations created during a certain date. | during:1647382306 List conversations that contain messages or comments created on Tue Mar 15 2022 GMT+0000 |
custom_field | Searches for conversations where a custom field has the given value. The syntax is You can use the Update conversation API endpoint or a "Update custom field" rule in Front to update the custom fields of a conversation. | custom_field:"External ID=12345" Lists conversations that contain a custom field called "External ID" with a value of "12345". |
Search across multiple filters
To search for conversations using multiple filters at once, separate the filters with a space. You can search up to 15 filters simultaneously.
The query syntax for multiple filters is as follows:
<filter_name>:<filter_value> <filter_name>:<filter_value>
For example, to search for conversations that have been sent to “example@example.com” and have the status “snoozed”, use the following query:
is:snoozed to:example@example.comis%3Asnoozed%20to%3Aexample%40example.comHow filters interact with each other
When searching across multiple filters, results are limited to conversations that match all the filters specified. In other words, the search filters are combined with AND logic.
For example, when using a query that specifies a recipient and a tag, the results include only the conversations that include the recipient AND the tag. The results do not include conversations that match on the recipient but not the tag, or vice versa.
The following query returns conversations tagged with a tag ID of tag_16qsy5 and in which “dale.cooper@frontapp.com” is a recipient.
recipient:dale.cooper@frontapp.com tag:tag_16qsy5recipient%3Adale.cooper%40frontapp.com%20tag%3Atag_16qsy5Exception to the filter interaction rule
The following filters use OR logic whenever you include multiple instances of the same filter in the search query (that is, the exception applies to from:example1@example.com from:example2@example.com but not from:example1@example.com to:example2@example.com)
- from
- to
- cc
- bcc
For example, if you search for conversations from “dale.cooper@frontapp.com” or “laura.palmer@frontapp.com”, the API returns conversation from either Dale OR Laura.
from:dale.cooper@frontapp.com from:laura.palmer@frontapp.comfrom%3Adale.cooper%40frontapp.com%20from%3Alaura.palmer%40frontapp.comHowever, if you search for conversations from “dale.cooper@frontapp.com” to “laura.palmer@frontapp.com”, the API only returns conversations that were sent from Dale AND in which Laura received the conversation.
from:dale.cooper@frontapp.com to:laura.palmer@frontapp.comfrom%3Adale.cooper%40frontapp.com%20to%3Alaura.palmer%40frontapp.comSimilarly, if you combine multiple instances of the from, to, cc, or bcc filters with any other filter, the API returns conversations that match on any of the recipient filters AND the rest of the query. For example, if you search for conversations that CC “dale.cooper@frontapp.com” or “laura.palmer@frontapp.com” and include a tag filter for the tag ID tag_16qsy5m, the API returns conversations that have the tag ID tag_16qsy5m AND were sent as CC to either Dale OR Laura.
cc:dale.cooper@frontapp.com cc:laura.palmer@frontapp.com tag:tag_16qsy5cc%3Adale.cooper%40frontapp.com%20cc%3Alaura.palmer%40frontapp.com%20tag%3Atag_16qsy5Conversation statuses
If you are filtering conversations by the is filter, the following information will be helpful to you. Conversation statuses have a bit of complexity in how they relate to each other (an "assigned" conversation cannot be "unassigned", but it can be "open", although it cannot be "open" and "archived"). Refer to the following tables to learn more about these relationships.
Status | Cannot be status | Description |
|---|---|---|
|
| Conversations with an assignee |
|
| Conversation without an assignee |
|
| Conversation in the Archived inbox tab |
|
| Conversations in the Trash inbox tab |
|
| Conversations in the Open inbox tab |
|
| Conversations in the Snoozed inbox tab (will reopen at a later date) |
| Conversations where the last message was inbound |
Example: Given the above information, you could search for a conversation that is:assigned and is:archived, but it would not make sense to also include is:trashed within that same filter because it conflicts with the archived filter.
Furthermore, it maybe helpful to see how these filters relate to the status field returned by Conversation responses. This field only returns four statuses compared to the seven search filters that exist, so there is overlap between the states represented by the conversation response status and the filter combinations. The conversation responses have additional properties in their response that round out the information received.
The following table describes this relationship.
value | Description | Conversation search filters |
|---|---|---|
| Open and unassigned |
|
| Open and assigned |
|
| Either:
|
|
| Trashed (assigned or unassigned) |
|
Example: Given the above information, if you were looking for conversations that are open and unassigned, you would use the filters is:open and is:unassigned to filter for them. The conversations returned by the search endpoint would include a status value of unassigned (they would never have a status value of opened) and would have an assignee property equal to null.
Example: Conversely, if you were looking for conversations that are archived and unassigned, you would use the filters is:archived and is:unassigned to filter for them. The conversations returned by the search endpoint would include a status value of archived and would have an assignee property equal to null.
Example: If you were looking for conversations that are snoozed and assigned, you would use the filters is:snoozed and is:assigned to filter for them. The conversations returned by the search endpoint would include a status value of archived but would have scheduled_reminders and assignee properties that are not null or empty.
Putting it all together
The following example is a complex query that searches from conversations that:
- Contain the phrase “the owls are not what they seem”
- Contain the word “blue”
- Have messages from dale.cooper@frontapp.com or laura.palmer@frontapp.com
- Are tagged with the tag ID tag_14nmdp
- Contain messages created before Tue Apr 19 2022 10:30 GMT+0000
"the owls are not what they seem" blue from:dale.cooper@frontapp.com from:laura.palmer@frontapp.com tag:tag_14nmdp before:1650364200%22the%20owls%20are%20not%20what%20they%20seem%22%20blue%20from%3Adale.cooper%40frontapp.com%20from%3Alaura.palmer%40frontapp.com%20tag%3Atag_14nmdp%20before%3A1650364200https://api2.frontapp.com/conversations/search/%22the%20owls%20are%20not%20what%20they%20seem%22%20blue%20from%3Adale.cooper%40frontapp.com%20from%3Alaura.palmer%40frontapp.com%20tag%3Atag_14nmdp%20before%3A1650364200Updated 26 days ago