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 shipment

https://api2.frontapp.com/conversations/search/lost%20shipment

https://api2.frontapp.com/conversations/search/is:archived is:unassigned

https://api2.frontapp.com/conversations/search/is%3Aarchived%20is%3Aunassigned

Access

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”

feedback

feedback

Example: Search for “feedback” and “urgent”

Separate multiple words with a space. The API only returns results that include all the words searched for.

feedback urgent

feedback%20urgent

Example: 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%22

Example: Search for conversations sent to the email address “[email protected]”

to:[email protected]

to%3Aexample%40example.com

👍
Tip
You can search across multiple filters simultaneously.

Example: Search for conversations sent to the email address “[email protected]” that contain the word “conference” in the subject or body

conference to:[email protected]

conference%20to%3Aexample%40example.com

👍
Tip
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:[email protected] Lists conversations in which a recipient has the email address [email protected]
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.	from:[email protected] Lists conversations sent from the email address [email protected]
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.	to:[email protected] Lists conversations sent to the email address [email protected]
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.	cc:[email protected] Lists conversations CC’ed to the email address [email protected]
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.	bcc:[email protected] Lists conversations BCC’ed to the email address [email protected]
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: `archived` `assigned` `open` `resolved` `snoozed` `trashed` `unassigned` `unreplied` `waiting` 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 Tue Mar 15 2022 10:12 pm GMT+0000
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 Tue Mar 15 2022 10:12 pm GMT+0000
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 `custom_field:<name>=<value>`. Because the name can contain whitespace, you can quote the entire query: `custom_field:"<name>=<value>"`. 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".

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:[email protected]

Lists conversations in which a recipient has the email address [email protected]

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.

from:[email protected]

Lists conversations sent from the email address [email protected]

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.

to:[email protected]

Lists conversations sent to the email address [email protected]

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.

cc:[email protected]

Lists conversations CC’ed to the email address [email protected]

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.

bcc:[email protected]

Lists conversations BCC’ed to the email address [email protected]

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.