Using In-place Search for Gmail

When preserving a Gmail or Google Workspace (formerly called G Suite) mailbox using the Gmail API, it is possible to perform pre-acquisition searches to narrow down the data set. You can perform in-place searches in Gmail and Google Calendar by clicking the "Perform Pre-Acquisition Search" link as shown below.

FEC allows you to execute your search query on the server side and preview the search results. Because FEC uses Gmail and Google Calendar APIs, the search syntax and functionality are identical to those of Gmail and Google Calendar search. In other words, the accuracy of the search results is dependent on the capabilities of Gmail and Google Calendar search.

FEC's in-place search for Gmail has two tabs:

The visibility of each tab depends on the folder selection made in the folder tree before launching in-place search. If both Gmail and Google Calendar items are selected for acquisition, then both tabs would be visible.

1. Gmail

What You Can Search For

Pre-acquisition filtering can be a convenient way to filter messages using a long list of criteria. You can refer to Google's documentation on search operators you can use with Gmail for a comprehensive list of search operators and syntax.

Here are a few examples to get you started:

Messages with a certain label — Example: label:business
Messages from a specific sender — Example: from:johndoe@example.com
Messages sent after a certain date — Example: after:2017/01/01
Messages with a specific ID — Example: rfc822msgid:2011203292@example.com
Messages that are important or starred — Example: is:important OR is:starred (note that the Boolean operator OR is capitalized)
Messages with specific words near each other — Example: business AROUND 3 meeting (matches items where "business" and "meeting" are within 3 words of each other)
Messages that are unread and have a pdf attachment — Example: is:unread filename:pdf (multiple search terms are combined with an AND by default)
Messages containing an exact phrase — Example: "business meeting tomorrow"
Messages containing all specified terms; not necessarily as a phrase — Example: (lunch dinner)
Messages in any folder, including Spam and Trash — Example: in:anywhere
Messages that do not have a label — Example: has:nouserlabels

Note: Google's API documentation states the following about date searches:

"All dates used in the search query are interpreted as midnight on that date in the PST timezone. To specify accurate dates for other timezones pass the value in seconds instead."

Contrary to Google's statement above, we've found during our testing in May, 2022 that Gmail API interprets date searches in UTC even when entered in yyyy/mm/dd format.

Epoch Date Search Example: after:1613106000 before:1613109600

The above query searches for February 12, 2021, 5:00 AM (UTC) to February 12, 2021, 6:00 AM (UTC)

Note: When referencing labels with spaces in their names, Gmail expects that the spaces be replaced with dashes. For example, you can search for all emails labeled "House Purchase" by using the query "in:house-purchase".

Boolean AND, OR, NOT Operators

When you use multiple search terms, Gmail search combines them with an invisible AND operator. In other words, the query in:inbox is:starred looks for items that are both in the Inbox, AND are starred.

If you would like to perform an OR search instead (e.g., when searching for messages that have a list of labels), you can include an explicit OR operator (capitalized) in your query. For example, searching for in:purchases OR in:expenses would cause Gmail to look for messages that have either the "Purchases" or "Expense" labels.

Example Searches

Example 1—Items that have the "Finance" label with dates after August 1, 2017 where the phrase "wall street" appears within 5 words of the word "mortgage":

"wall street" AROUND 5 mortgage after:2017/8/1 in:Finance

Example 2—Items that have either the "Apple" or the "Samsung" label with dates between July 5, 2016 and September 3, 2017 that contain the domains "verizon.com" or "att.com":

(verizon.com OR att.com) (in:Apple OR in:Samsung) after:2016/7/5 before:2017/9/3

Example 3—Items from "john.doe@example.com" that contain the word "recipe" in their subjects that are newer than 3 months:

from:john.doe@example.com subject:recipe newer_than:3m

Example 4—An item with a specific message ID:

rfc822msgid:faa8eb4ef3a111cef92c4f3d4.2b2e377f4b.20180727131804.f6cb5c2de6.514dd497@mail117.wdc01.mcdlv.net

Example 5—Items that do not have the "Work Product" label where the word "Apple" is found within 4 words of the word "Sonos" and "Apple" appears first (i.e., the proximity search is order sensitive):

"Apple AROUND 4 Sonos" NOT in:work-product

2. Google Calendar

While Google Calendar API allows end users to perform searches, its search capabilities are different than those of Gmail.

The search bar at the top allows you to enter free text search terms to find events that match these terms in any field, except for extended properties. It is important that you do not enter search operators such as "before:", "after:", etc. here as you would in Gmail.

The two date pickers below allow you to filter events by their start and end times in Coordinated Universal Time (UTC). You could populate none, one, or both of these date parameters depending on your requirements.

Saving the Search Query

Once you have finalized your search query, you can save it by using the "Save" button. This will close the in-place search window and activate your query. You will see a notice as in the screenshot below.

Clearing the Search Query

If you would like to clear the search query, you can click on the small (x) symbol next to the "Search Query Activated" text as shown in the figure above.

Limitations of Gmail Search

The search functionality built into Gmail and utilized by FEC is limited to the documents that Gmail is able to recognize and index. For instance, a proprietary CAD file unrecognized by Gmail, or files inside an encrypted file archive would not be indexed or searched. Similarly, if a file has no extractable text (e.g., a scanned TIFF image of a document), Gmail would not be able to extract text from it or index it.

Given the above limitations, it may be appropriate to use the Gmail search functionality in FEC to filter messages by their labels, or top-level message characteristics such as sender, recipient and subject content. Keep these limitations in mind if you plan to use this functionality to perform a blanket search intended to search all documents and their attachments recursively.