| Authorization token required | true |
| Admin Authorization token required | false |
<SearchActionRequest> ## SearchActionRequest
<SearchRequest [warmup="(0|1)"] [includeTagDeleted="{include-items-tagged-for-delete} (0|1)"]
[includeTagMuted="{include-items-tagged-for-delete} (0|1)"]
[calExpandInstStart="{cal-item-expand-start-time-in-msec} (Long)"]
[calExpandInstEnd="{cal-item-expand-end-time-in-msec} (Long)"] [inDumpster="(0|1)"]
[types="{comma-sep-search-types}"] [groupBy="{deprecated-group-by}"] [quick="(0|1)"]
[sortBy="{sort-by}"] [fetch="..."] [read="{mark-as-read} (0|1)"]
[max="{max-inlined-length} (Integer)"] [html="{want-html} (0|1)"]
[needExp="{need-can-expand} (0|1)"] [neuter="{neuter-images} (0|1)"]
[recip="{want-recipients} (0 | 1 | 2 | false | true)"] [prefetch="(0|1)"]
[resultMode="{result-mode}"] [fullConversation="{full-conversation} (0|1)"]
[field="{default-field}"] [limit="(Integer)"] [offset="(Integer)"]
[wantContent="{want-content} (full | original | both)"] [memberOf="{include-member-of} (0|1)"]> ## SearchRequest
<query>{query} (String)</query>
(<header n="{attribute-name}" /> ## AttributeName)*
<tz id="{timezone-id}" stdoff="{timezone-std-offset} (Integer)"
dayoff="{timezone-daylight-offset} (Integer)" [stdname="..."] [dayname="..."]> ## CalTZInfo
<standard [week="{tzonset-week} (Integer)"] [wkday="{tzonset-day-of-week} (Integer)"]
mon="{tzonset-month} (Integer)" [mday="{tzonset-day-of-month} (Integer)"]
hour="{tzonset-hour} (Integer)" min="{tzonset-minute} (Integer)"
sec="{tzonset-second} (Integer)" /> ## TzOnsetInfo
<daylight ... /> ## See /SearchRequest/tz/standard [ ## TzOnsetInfo]
</tz>
<locale>{locale} (String)</locale>
<cursor [id="{cursor-prev-id}"] [sortVal="{cursor-sort-value}"] [endSortVal="{cursor-end-sort-value}"]
[includeOffset="{cursor-include-offset} (0|1)"] /> ## CursorInfo
</SearchRequest>
<BulkAction op="{operation} (move | read | unread)" [l="{folder-path}"] /> ## BulkAction
</SearchActionRequest>
elements and attributes you can define within a
<SearchActionRequest> element:
| XPath | Required / Optional | Description | ||||||
| /SearchRequest | Required (only 1) | Search request | ||||||
| /SearchRequest@warmup | Optional (0 or 1) | Type: 0|1 Warmup: When this option is specified, all other options are simply ignored, so you can't include this option in regular search requests. This option gives a hint to the index system to open the index data and primes it for search. The client should send this warm-up request as soon as the user puts the cursor on the search bar. This will not only prime the index but also opens a persistent HTTP connection (HTTP 1.1 Keep-Alive) to the server, hence smaller latencies in subseqent search requests. Sending this warm-up request too early (e.g. login time) will be in vain in most cases because the index data is evicted from the cache due to inactivity timeout by the time you actually send a search request. |
||||||
| /SearchRequest@includeTagDeleted | Optional (0 or 1) | Type: 0|1 Set to 1 (true) to include items with the \Deleted tag set in results |
||||||
| /SearchRequest@includeTagMuted | Optional (0 or 1) | Type: 0|1 Set to 1 (true) to include items with the \Muted tag set in results |
||||||
| /SearchRequest@calExpandInstStart | Optional (0 or 1) | Type: Long Start time in milliseconds for the range to include instances for calendar items from. If calExpandInstStart and calExpandInstEnd are specified, and the search types include calendar item types (e.g. appointment), then the search results include the instances for calendar items within that range in the form described in the description of the response. ***IMPORTANT NOTE: Calendar Items that have no instances within that range are COMPLETELY EXCLUDED from the results (e.g. not even an <appt> element. Calendar Items with no data (such as Tasks with no date specified) are included, but with no instance information*** |
||||||
| /SearchRequest@calExpandInstEnd | Optional (0 or 1) | Type: Long End time in milliseconds for the range to include instances for calendar items from. |
||||||
| /SearchRequest@inDumpster | Optional (0 or 1) | Type: 0|1 Set this flat to 1 (true) to search dumpster data instead of live data. |
||||||
| /SearchRequest@types | Optional (0 or 1) | Type: String Comma separated list of search types Legal values are: conversation|message|contact|appointment|task|wiki|document Default is "conversation". NOTE: only ONE of message, conversation may be set. If both are set, the first is used. |
||||||
| /SearchRequest@groupBy | Optional (0 or 1) | Type: String Deprecated. Use {comma-sep-search-types} instead |
||||||
| /SearchRequest@quick | Optional (0 or 1) | Type: 0|1 "Quick" flag. For performance reasons, the index system accumulates messages with not-indexed-yet state until a certain threshold and indexes them as a batch. To return up-to-date search results, the index system also indexes those pending messages right before a search. To lower latencies, this option gives a hint to the index system not to trigger this catch-up index prior to the search by giving up the freshness of the search results, i.e. recent messages may not be included in the search results. |
||||||
| /SearchRequest@sortBy | Optional (0 or 1) | Type: String SortBy setting. Default value is "dateDesc" Possible values: none|dateAsc|dateDesc|subjAsc|subjDesc|nameAsc|nameDesc|rcptAsc|rcptDesc|attachAsc|attachDesc|flagAsc|flagDesc| priorityAsc|priorityDesc|idAsc|idDesc|readAsc|readDesc If {sort-by} is "none" then cursors MUST NOT be used, and some searches are impossible (searches that require intersection of complex sub-ops). Server will throw an IllegalArgumentException if the search is invalid. ADDITIONAL SORT MODES FOR TASKS: valid only if types="task" (and task alone): taskDueAsc|taskDueDesc|taskStatusAsc|taskStatusDesc|taskPercCompletedAsc|taskPercCompletedDesc |
||||||
| /SearchRequest@fetch | Optional (0 or 1) | Type: String Select setting for hit expansion. if fetch="1" (or fetch="first") is specified, the first hit will be expanded inline (messages only at present) if fetch="{item-id}", only the message with the given {item-id} is expanded inline if fetch="{item-id-1,item-id-2,...,item-id-n}", messages with ids in the comma-separated list will be expanded if fetch="all", all messages are expanded inline if fetch="!", only the first message in the conversation will be expanded, whether it's a hit or not if fetch="u" (or fetch="unread"), all unread hits are expanded if fetch="u1" (or fetch="unread-first"), if there are any unread hits, they are expanded, otherwise the first hit is expanded. if fetch="u1!", if there are any unread hits, they are expanded, otherwise the first hit and the first message are expanded (those may be the same) if fetch="hits", all hits are expanded if fetch="hits!", all hits are expanded if there are any, otherwise the first message is expanded + if html="1" is also specified, inlined hits will return HTML parts if available + if read="1" is also specified, inlined hits will be marked as read + if neuter="0" is also specified, images in inlined HTML parts will not be "neutered" + if <header>s are requested, any matching headers are included in inlined message hits + if max="{max-inlined-length}" is specified, inlined body content in limited to the given length; if the part is truncated, truncated="1" is specified on the <mp> in question |
||||||
| /SearchRequest@read | Optional (0 or 1) | Type: 0|1 Inlined hits will be marked as read |
||||||
| /SearchRequest@max | Optional (0 or 1) | Type: Integer If specified, inlined body content in limited to the given length; if the part is truncated, truncated="1" is specified on the <mp> in question |
||||||
| /SearchRequest@html | Optional (0 or 1) | Type: 0|1 Set to 1 (true) to cause inlined hits to return HTML parts if available |
||||||
| /SearchRequest@needExp | Optional (0 or 1) | Type: 0|1 If 'needExp' is set in the request, two additional flags may be included in <e> elements for messages returned inline.
|
||||||
| /SearchRequest@neuter | Optional (0 or 1) | Type: 0|1 Set to 0 (false) to stop images in inlined HTML parts from being "neutered" |
||||||
| /SearchRequest@recip | Optional (0 or 1) | Type: 0 | 1 | 2 | false | true Setting specifying which recipients should be returned.
|
||||||
| /SearchRequest@prefetch | Optional (0 or 1) | Type: 0|1 Prefetch |
||||||
| /SearchRequest@resultMode | Optional (0 or 1) | Type: String Specifies the type of result.
|
||||||
| /SearchRequest@fullConversation | Optional (0 or 1) | Type: 0|1 By default, only matching messages are included in conversation results. Set to 1 (true) to include all messages in the conversation, even if they don't match the search, including items in Trash and Junk folders. |
||||||
| /SearchRequest@field | Optional (0 or 1) | Type: String By default, text without an operator searches the CONTENT field. By setting the {default-field} value, you can control the default operator. Specify any of the text operators that are available in query.txt, e.g. 'content:' [the default] or 'subject:', etc. The date operators (date, after, before) and the "item:" operator should not be specified as default fields because of quirks in the search grammar. |
||||||
| /SearchRequest@limit | Optional (0 or 1) | Type: Integer The maximum number of results to return. It defaults to 10 if not specified, and is capped by 1000 |
||||||
| /SearchRequest@offset | Optional (0 or 1) | Type: Integer Specifies the 0-based offset into the results list to return as the first result for this search operation. For example, limit=10 offset=30 will return the 31st through 40th results inclusive. |
||||||
| /SearchRequest@wantContent | Optional (0 or 1) | Type: full | original | both used by clients if they want mail content with/without quoted text |
||||||
| /SearchRequest@memberOf | Optional (0 or 1) | Type: 0|1 If set, Include the list of contact groups this contact is a member of. Note: use sparingly, there is a performance penalty associated with computing this information |
||||||
| /SearchRequest/query | Optional (0 or 1) | Type: {query} (String) Query string |
||||||
| /SearchRequest/header | Optional (0 or more) | if <header>s are requested, any matching headers are included in inlined message hits | ||||||
| /SearchRequest/header@n | Required (only 1) | Type: String Attribute name |
||||||
| /SearchRequest/tz | Optional (0 or 1) | Timezone specification | ||||||
| /SearchRequest/tz@id | Required (only 1) | Type: String Timezone ID. If this is the only detail present then this should be an existing server-known timezone's ID Otherwise, it must be present, although it will be ignored by the server |
||||||
| /SearchRequest/tz@stdoff | Required (only 1) | Type: Integer Standard Time's offset in minutes from UTC; local = UTC + offset |
||||||
| /SearchRequest/tz@dayoff | Required (only 1) | Type: Integer Daylight Saving Time's offset in minutes from UTC; present only if DST is used |
||||||
| /SearchRequest/tz@stdname | Optional (0 or 1) | Type: String Standard Time component's timezone name |
||||||
| /SearchRequest/tz@dayname | Optional (0 or 1) | Type: String Daylight Saving Time component's timezone name |
||||||
| /SearchRequest/tz/standard | Optional (0 or 1) | Time/rule for transitioning from daylight time to standard time. Either specify week/wkday combo, or mday. | ||||||
| /SearchRequest/tz/standard@week | Optional (0 or 1) | Type: Integer Week number; 1=first, 2=second, 3=third, 4=fourth, -1=last |
||||||
| /SearchRequest/tz/standard@wkday | Optional (0 or 1) | Type: Integer Day of week; 1=Sunday, 2=Monday, etc. |
||||||
| /SearchRequest/tz/standard@mon | Required (only 1) | Type: Integer Month; 1=January, 2=February, etc. |
||||||
| /SearchRequest/tz/standard@mday | Optional (0 or 1) | Type: Integer Day of month (1..31) |
||||||
| /SearchRequest/tz/standard@hour | Required (only 1) | Type: Integer Transition hour (0..23) |
||||||
| /SearchRequest/tz/standard@min | Required (only 1) | Type: Integer Transition minute (0..59) |
||||||
| /SearchRequest/tz/standard@sec | Required (only 1) | Type: Integer Transition second; 0..59, usually 0 |
||||||
| /SearchRequest/tz/daylight | Optional (0 or 1) | Time/rule for transitioning from standard time to daylight time
See /SearchRequest/tz/standard for more details. |
||||||
| /SearchRequest/locale | Optional (0 or 1) | Type: {locale} (String) Client locale identification. Value is of the form LL-CC[-V+] where: LL is two character language code CC is two character country code V+ is optional variant identifier string See: ISO Language Codes: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt ISO Country Codes: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html |
||||||
| /SearchRequest/cursor | Optional (0 or 1) | Cursor specification | ||||||
| /SearchRequest/cursor@id | Optional (0 or 1) | Type: String Previous ID. cursor-prev-id and cursor-sort-value and correspond to the last hit on the current page (assuming you're going forward, if you're backing up then they should be the first hit on the current page) or the selected item before changing the sort order. cursor-sort-value should be set to the value of the 'sf' (SortField) attribute. If you are changing the sort field, don't specify sortVal because 'sf' is sort field dependent. (In this case, the server supplements sortVal using the specified item ID. If the item no longer exist, the cursor gets cleared.) The server uses those attributes to find the spot in the new results that corresponds to your old position: even if some entries have been removed or added to the search results (e.g. if you are searching is:unread and you read some). |
||||||
| /SearchRequest/cursor@sortVal | Optional (0 or 1) | Type: String Should be set to the value of the 'sf' (SortField) attribute. See description for cursor-prev-id for more information. |
||||||
| /SearchRequest/cursor@endSortVal | Optional (0 or 1) | Type: String Used for ranges to tell the cursor where to stop (non-inclusive) returning values |
||||||
| /SearchRequest/cursor@includeOffset | Optional (0 or 1) | Type: 0|1 If true, the response will include the cursor position (starting from 0) in the entire hits. This can't be used with text queries. Don't abuse this option because this operation is relatively expensive |
||||||
| /BulkAction | Required (only 1) | Bulk action | ||||||
| /BulkAction@op | Required (only 1) | Type: move | read | unread Operation to perform
|
||||||
| /BulkAction@l | Optional (0 or 1) | Type: String Required if op="move". Folder pathname where all matching items should be moved. |
<SearchActionResponse /> ## SearchActionResponse