Building Search Queries

Learn how to construct search queries.

Introduction

Using the /api/archive/search endpoint you can easily add Mimecast search capability to your applications and scripts as an end user or an administrator. The search query is created in XML format allowing for the use of element values and attributes to offer extremely flexible search parameters and filters that cater for both very simple and very advanced queries.

While the query is created in XML it should be sent to the API as a string parameter value in the standard API JSON payload.

Examples

Below is an example of a complete XML query string displaying all available elements.

Defining which mailboxes to search

You can define 1 or more mailboxes to search by adding <mailbox/> elements as child elements of the <mailboxes/> element. Alternatively if you want to perform an administrator search you can remove the <mailboxes/> element completely to search the entire archive. For example to search across 2 mailboxes, add the <mailboxes/> element as a child of the <metadata/> element:

Searching for words in message attachments

Set the value of the <docs/> child element of the <muse/> element to search for text in attachments. For example,

<docs select="SET FILE TYPE HERE">search for this text</docs>

Apply a date filter

Use the <date/> child element of the <muse/> element to apply a date filter. For example,

<date select="INSERT VALUE HERE"/>

Where:

Attribute

Required

Values

Description

select

Required if the date element is included in the query

today

yesterday

last_week

last_month

last_year

between

Queries for messages received during the time period defined.

from

Required if the select attribute is set to to between

Date string in the following format: 2015-09-21T23:00:00Z

Queries for messages received after this date and time.

to

Required if the select attribute is set to to between

Date string in the following format: 2015-09-21T23:00:00Z

Queries for messages received before this date and time.

Advanced

Conditional Operators and Isolation

Within the text element, 2 conditional operators are support; AND / OR. For example a search of the form:

hello OR greetings

will return results with all messages that have either the word "hello" or "greetings" in them, and of course those messages that have both words.

However, a search of the form:

hello and greetings

will return results with all messages that have both the words "hello" and "greetings" in them. The AND operator is inferred by default.

To isolate terms, you can nest brackets to any level. In this way it is possible to make compound searches, for example:

subject: (merry and xmas) or (happy and (easter or birthday))

will match message subjects with the following form:

merry xmas

happy easter

happy birthday

but WILL NOT match these subjects:

merry birthday

happy

merry happy

Operator Precedence

Where both AND and OR operators are used the OR operator takes precedence.

Consequently a search of this form:

subject: happy and birthday or easter

is equivalent to

subject: (happy and birthday) or (happy and easter)

but not equivalent to

subject: (happy and birthday) or (easter)

As the "and" operator is inferred, the search could also be written as:

subject: happy birthday or easter

Proximity Searches / Literals

There are times when a search requires a literal combination of words to form a particular phrase. A simple search using keywords just matches any occurrence of the keyword, but not the presence of a particular phrase.

For example, a search of the form:

body: happy easter

would match messages with the words "happy" and "easter" anywhere in the message body. It would also match the phrase "happy easter" directly, but the user might intend to find only that phrase.

An example of a mismatch is a body of the type:

Easter is almost upon us. I will be happy when it's over.

The message body matches because it contains both words "happy" and "easter". But this is clearly not the intent of the search.

In these cases the phrase can be established using double quotes. This would make the match a "proximity" match for the constituent words of the phrase. For example,

body: "happy easter"

would not match the above "Easter is almost upon us..." phrase, but would match occurrences of the words "happy" and "easter" appearing next to each other in the message body.

More Complex Queries Using Field Combinations

You can use left-to-right reading of field restrictions. This makes it possible to combine multiple field restrictions into 1 complex query.

For example, we might choose to search for emails from a particular sender containing a particular keyword in the message body. For example,

from: auser@mimecast.com and body: "welcome to the party" or subject: greetings

In this example the field restriction applies in a left-to-right reading order. Now consider this example:

body: welcome or hello or subject: greetings

Here the search will match messages with a body containing either "welcome" or "hello" or with a subject "greetings".

Field Isolation

You can also use bracketing with field restrictions, so that complex queries can be specified in isolation.

Rather than restructuring complex queries to fit the left-to-right field context matching, field delimiters can be included in brackets. For example,

((subject: greetings) or (from: bob)) and (body: "good day")

This has the effect of grouping within scope of the enclosing brackets. It is a powerful mechanism for complex queries, but means the user must pay attention to the scope of the field delimiter when using nested brackets. For example,

(body: happy and (from: steve) or bob)

implies the "body:" scope is also applied to "bob", as the bracket scope around "from: steve" has been closed. Consequently, remembering that "or" takes precedence, this is comparable to,

(body: happy) and ((from: steve) or (body: bob))

It is important to pay close attention to early-closing of a scoped field delimited block. If no field delimiter is provided then by inference the five fields (subject, body, from, to and headers) are applied. Therefore if a search term falls outside a bracket-scoped block then the search will look across all 5 message components. For example,

(subject: greetings) and hello

This is equivalent to searching for a subject containing the word "greetings" and the appearance of the word "hello" in any of the five default fields,