IMAP_Search

The IMAP_Search command searches for messages that match the given search criteria in the current mailbox. searchCriteria consists of one or more search keys. msgNumArray returns a listing of message sequence numbers corresponding to those messages that match the search criteria.
msgNumArray returns a listing of message sequence numbers corresponding to those messages that match the searching criteria.

imap_ID is a long integer reference to an open connection created with IMAP_Login.

searchCriteria is a text parameter listing one or more search keys (see “Authorized search keys” at the end of this paragraph) associated or not with values to look for. A search key may be a single item or can also be a parenthesized list of one or more search keys. For example:

SearchKey1 = FLAGGED
SearchKey2 = NOT FLAGGED
SearchKey3 = FLAGGED DRAFT

Note: Matching is usually not case-sensitive.

• If the searchCriteria is a null string, the search will be equivalent to a “select all”:
  
   IMAP_Search(imap_ID;"";msgNumArray)
  
  ... returns all messages in the current working mailbox.

• If the searchCriteria includes multiple search keys, the result is the intersection (AND function) of all the messages that match those keys.
  searchCriteria = FLAGGED FROM "SMITH"
  ... returns all messages with \Flagged flag set AND sent by Smith.

• You can use the OR or NOT operators as follows:
  searchCriteria = OR SEEN FLAGGED
  ... returns all messages with \Seen flag set OR \Flagged flag set
  searchCriteria = NOT SEEN
  ... returns all messages with \Seen flag not set .
  searchCriteria = HEADER CONTENT-TYPE "MIXED" NOT HEADER CONTENT-TYPE "TEXT"...
  ... returns message whose content-type header contains “Mixed” and does not contain “Text”.
  searchCriteria = HEADER CONTENT-TYPE "E" NOT SUBJECT "o" NOT HEADER CONTENT-TYPE "MIXED"
  ... returns message whose content-type header contains “ e ” and whose Subject header does not contain “ o ” and whose content-type header is not “ Mixed ”.
  searchCriteria = OR (ANSWERED SMALLER 400) (HEADER CONTENT-TYPE "E" NOT SUBJECT "o" NOT HEADER CONTENT-TYPE "MIXED")
  ... returns messages matching the first parenthesized list OR the second one.
  searchCriteria = OR ANSWERED SMALLER 400 (HEADER CONTENT-TYPE "E" NOT SUBJECT "o" NOT HEADER CONTENT-TYPE "MIXED")
  ... returns messages matching with \Answered flag set OR messages whose size is smaller than 400 bytes AND the parenthesized list as specified.

As concerns the last two examples, notice that the result of the search is different when you remove the parentheses of the first search key list.

• The searchCriteria may include the optional [CHARSET] specification. This consists of the "CHARSET" word followed by a registered [CHARSET] (US ASCII, ISO-8859). It indicates the charset of the searchCriteria string. Therefore, you must convert the searchCriteria string into the specified charset if you use the [CHARSET] specification (see the 4D Mac to ISO command).
  By default, 4D Internet Commands encode in Quotable Printable the searchCriteria string if it contains extended characters.
  searchCriteria = CHARSET "ISO-8859" BODY "Help"
  ... means the search criteria uses the charset iso-8859 and the server will have to convert the search criteria before searching, if necessary.

Search-keys may request the value to search for:

• Search-keys with a date value

<date> is a string that must be formatted as follows: date-day+"-"+date-month+"-"+date-year where date-day indicates the number of the day of the month (max. 2 characters), date-month indicates the name of the month (Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Dec) and date-year indicates the year (4 characters).

Example: searchCriteria = SENTBEFORE 1-Feb-2000 (a date does not usually need to be quoted since it does not contain any special characters)

• Search-keys with a string value

<string> may contain any character and must be quoted. If the string does not contain any special characters, like the space character for instance, it does not need to be quoted. Quoting such strings will ensure that your string value will be correctly interpreted.

Example: searchCriteria = FROM "SMITH"

Note: For all search keys that use strings, a message matches the key if the string is a substring of the field. Matching is not case-sensitive.

• Search-keys with a field-name value

<field-name> is the name of a header field.

Example: searchCriteria = HEADER CONTENT-TYPE "MIXED"

• Search-keys with a flag value

<flag> may accept one or several keywords (including standard flags), separated by spaces.

Example: searchCriteria = KEYWORD \Flagged \Draft

• Search-keys with a message set value

Identifies a set of messages. For message sequence numbers, these are consecutive numbers from 1 to the total number of messages in the mailbox.
A comma delimits individual numbers; a colon delimits between two numbers inclusive.

Examples:
2,4:7,9,12:* is 2,4,5,6,7,9,12,13,14,15 for a mailbox with 15 messages.

searchCriteria = 1:5 ANSWERED search in message selection from message sequence number 1 to 5 for messages which have the \Answered flag set.

searchCriteria= 2,4 ANSWERED search in the message selection (message numbers 2 and 4) for messages which have the \Answered flag set.

ALL: All messages in the mailbox.

ANSWERED: Messages with the \Answered flag set.

UNANSWERED: Messages that do not have the \Answered flag set.

DELETED: Messages with the \Deleted flag set.

UNDELETED: Messages that do not have the \Deleted flag set.

DRAFT: Messages with the \Draft flag set.

UNDRAFT: Messages that do not have the \Draft flag set.

FLAGGED: Messages with the \Flagged flag set.

UNFLAGGED: Messages that do not have the \Flagged flag set.

RECENT: Messages that have the \Recent flag set.

OLD: Messages that do not have the \Recent flag set.

SEEN: Messages that have the \Seen flag set.

UNSEEN: Messages that do not have the \Seen flag set.

NEW: Messages that have the \Recent flag set but not the \Seen flag. This is functionally equivalent to “(RECENT UNSEEN)”.

KEYWORD <flag>: Messages with the specified keyword set.

UNKEYWORD <flag>: Messages that do not have the specified keyword set.

BEFORE <date>: Messages whose internal date is earlier than the specified date.

ON <date>: Messages whose internal date is within the specified date.

SINCE <date>: Messages whose internal date is within or later than the specified date.

SENTBEFORE <date>: Messages whose Date header is earlier than the specified date.

SENTON <date>: Messages whose Date header is within the specified date.

SENTSINCE <date>: Messages whose Date header is within or later than the specified date.

TO <string>: Messages that contain the specified string in the TO header.

FROM <string>: Messages that contain the specified string in the FROM header.

CC <string>: Messages that contain the specified string in the CC header.

BCC <string>: Messages that contain the specified string in the BCC header.

SUBJECT <string>: Messages that contain the specified string in the Subject header.

BODY <string>: Messages that contain the specified string in the message body.

TEXT <string>: Messages that contain the specified string in the header or in the message body.

HEADER <field-name> <string>: Messages that have a header with the specified field-name and that contain the specified string in the field-body.

UID <message UID>: Messages with unique identifiers corresponding to the specified unique identifier set.

LARGER <n>: Messages with a size larger than the specified number of bytes.

SMALLER <n>: Messages with a size smaller than the specified number of bytes.

NOT <search-key>: Messages that do not match the specified search key.

OR <search-key1> <search-key2>: Messages that match either search key.