Use API For Building Search Queries In XML | Mimecast

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.

<?xml version="1.0"?>
    <xmlquery trace="iql,muse">
    <metadata query-type="emailarchive" archive="true" active="false" page-size="25" startrow="0">
        <mailboxes>
            <mailbox include-aliases="true">auser@mimecast.com</mailbox>
        </mailboxes>
        <smartfolders/>
        <return-fields>
            <return-field>attachmentcount</return-field>
            <return-field>status</return-field>
            <return-field>subject</return-field>
            <return-field>size</return-field>
            <return-field>receiveddate</return-field>
            <return-field>displayfrom</return-field>
            <return-field>displayfromaddress</return-field>
            <return-field>id</return-field>
            <return-field>displayto</return-field>
            <return-field>displaytoaddresslist</return-field>
            <return-field>smash</return-field>
        </return-fields>
    </metadata>
    <muse>
        <text></text>
        <date select="last_year"/>
        <sent></sent>
        <docs select="optional">
        </docs>
        <route/>
    </muse>
</xmlquery>

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:

<mailboxes>
    <mailbox include-aliases="true">auser@mimecast.com</mailbox>
    <mailbox include-aliases="true">anotheruser@mimecast.com</mailbox>
</mailboxes>

Searching for messages to or from a defined address

Use the <sent/> child element of the <muse/> element to filter on messages to or from a specific address. The element value can be an email address, domain (without the @ symbol), or a display name.

<sent select="from" mailbox="auser@mimecast.com">sender@mimecast.com</sent>

Where:

Attribute	Required	Values	Description
select	Required if the *sent* element is included in the query	"from" or "to"	Queries for messages sent to or sent from the email address defined in the element value.
mailbox	Optional	The mailbox that the query is limited to.	Queries for messages sent to or sent from the email address defined in the element value.

Searching for words in all message components

Use the <text/> child element of the <muse/> element to define the search text. For example,

<text>search for this text</text>

Searching for words in the message subject only

Use the subject: prefix in the <text/> child element of the <muse/> element to define the search text. For example,

<text>subject: search for this text</text>

Searching for words in the message body only

Use the body: prefix in the <text/> child element of the <muse/> element to define the search text. For example,

<text>body: search for this text</text>

Searching for words in the message headers only

Use the headers: prefix in the <text/> child element of the <muse/> element to define the search text. For example,

<text>headers: search for this text</text>

Searching for messages with attachments

Use the <docs/> child element of the <muse/> element to search for messages with attachments. For example,

<docs select="SET FILE TYPE HERE"></docs>

Where:

Attribute	Required	Values	Description
select	Required if the *docs* element is included in the query	optional - messages with and without attachments any - messages with any attachment documents - messages with doc, dot, docx, docm, dotx, dotm, pdf, rtf, html attachments spreadsheets - messages with xls, xlt, xlsx, xlsm, xltx, xltm, xlsb, xlam, csv attachments presentations - messages with ppt, pptx, pptm, potx, potm, ppam, ppsx, ppsm, sldx, sldm, thms, pps attachments text - messages with txt, text, html, log attachments images - messages with jpg, jpeg, png, bmp, gif, psd, tif, tiff attachments media - messages with mp3, mp4, m4a, mpg, mpeg, avi, wav, aac, wma, mov attachments zips - messages with zip, rar, cab, gz, gzip, 7z attachments none - No attachments are to be present in the results	Queries for messages with attachments of the defined type.

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,

(subject: greetings) and ((subject: hello) or (from: hello) or (to: hello) or (body: hello) or (headers: hello))