IMAP_MsgFetch

version 6.8.1

IMAP_MsgFetch (imap_ID; msgNum; msgDataItem; msgDataItemValue) Integer

The IMAP_MsgFetch command allows the user to request one or several basic data items for the specified message without downloading the message.

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

msgNum is a long integer value indicating the message to be checked. This value represents the position of a message within the current list of messages. You cannot rely on the msgNum remaining the same for a specific e-mail item from session to session.

msgDataItem is a text variable that indicates one or several data items you want to retrieve. In the case of several data items, a space character must separate each of them. There are two kinds of data items:

• Basic data items, which only retrieve one piece of information, and

• Macro data items, which retrieve several pieces of information, issued from basic data items at one time. Three macros specify commonly-used sets of data items and can be used in place of them. A macro must be used by itself, and not in conjunction with other macros or data items.

For more information on data items, see the "Basic data items" and "Macro data items" paragraphs below.

msgDataItemValue is a text variable that can return either a single DataItem/DataItemValue pair or a list of DataItem/DataItemValue pairs depending on the msgDataItem parameter value.

• In the case of a single DataItem/DataItemValue, the returned text structure is as follows: DataItem name+Space+DataItemValue

• In the case of a list of DataItem/DataItemValue pairs, the returned text structure is as follows: DataItem name1+Space+DataItemValue1+Space+DataItem name2+Space+DataItemValue2.

msgDataItemValue may contain a parenthesized list, a quoted string or a single string depending on the msgDataItem parameter.

• The parenthesized list is structured as follows (see FLAGS case for example): (FirstDataItemValue+space+2ndDataItemValue)

If the parenthesized list returns only parentheses, this means that there is no item value. This rule does not apply to address parenthesized lists (see ENVELOPE).

• Quoted strings are structured as follows (see INTERNALDATE case for example): DataItem name+Space+Quote+DataItemValue+Quote

If the DataItem value returns "", this means that it is a null string.

• Strings that are not quoted indicate integer, long integer or numeric values and are structured as follows: DataItem name+Space+DataItemValue.

In this case, you will most likely have to convert to the appropriate type (see UID case for example).

Note: Quotes are generally used when the string value includes special characters, such as a space or parentheses. As such, when you parse the resulting string of the IMAP_Fetch command, quote characters are taken into consideration when processing the string content.

• INTERNALDATE

Retrieves the internal date and time of the message on the IMAP server. This is not the date and time returned by the "Date" header, but rather a date and time that indicate when the message was received. For messages delivered via an SMTP server, this date usually reflects the date and time of the final delivery of the message. For messages sent after an IMAP_Copy command, this data usually reflects the internal date and time of the source message.

INTERNALDATE data item value returns a quoted string.

Example:

   msgDataItem:="INTERNALDATE"
   $Err:=IMAP_MsgFetch(imap_ID;1;msgDataItem;msgDataItemValue) 

msgDataItem returns INTERNALDATE "17-Jul-2001 15:45:37 +0200"

• FLAGS

Retrieves the parenthesized list of flags that are set for the specified message. Flags values are separated by spaces.

Example:

   msgDataItem:="FLAGS"
   $Err:=IMAP_MsgFetch(imap_ID;1;msgDataItem;msgDataItemValue) 

msgDataItem returns FLAGS () if there is no flag set for the specified message.

msgDataItem returns FLAGS (\Seen \Answered) if \Seen and \Answered flags are set for the specified message.

• RFC822.SIZE

Retrieves the number of bytes in the message, as expressed in RFC-822 format. The Data item is separated from the returned value by a space. An unquoted string is returned, which means you will probably need to convert this string into a longint value (see UID example).

Example:

   msgDataItem:="RFC822.SIZE"
   $Err:=IMAP_MsgFetch(imap_ID;1;msgDataItem;msgDataItemValue)

msgDataItem returns RFC822.SIZE 99599

• ENVELOPE

Retrieves the parenthesized list describing the header part for the specified message. The server computes this by parsing the message header and defaulting various fields where necessary.

The header fields are returned in the following order: date, subject, from, sender, reply-to, to, cc, bcc, in-reply-to, and message-id. The date, subject, in-reply-to and message-id fields are quoted strings:

Example:

   msgDataItem:="ENVELOPE"
   $Err:=IMAP_MsgFetch(imap_ID;1;msgDataItem;msgDataItemValue)

msgDataItem returns ENVELOPE ("Tue, 17 Jul 2001 17:26:34 +0200" "Test" (("RSmith" NIL "RSmith" "test")) (("RSmith" NIL "RSmith" "test")) (("RSmith" NIL "RSmith" "test")) (("RSmith" NIL "RSmith" "test")) () () "" "<ee6b33a.-1@Mail.x6foadRIbnm>")

Date:	"Tue, 17 Jul 2001 17:26:34 +0200"	date header
Subject:	"Test"	subject header
From:	(("RSmith" NIL "RSmith" "test"))	address structures
Sender:	(("RSmith" NIL "RSmith" "test"))	address structures
reply-to:	(("RSmith" NIL "RSmith" "test"))	address structures
to:	(("RSmith" NIL "RSmith" "test"))	address structures
cc:	()	Cc header not used
bcc:	()	Bcc header not used
in-reply-to:	""	In-reply-to header
message-id:	"<ee6b33a.-1@Mail.x6foadRIbnm>"	message-id header

The from, sender, reply-to, to, cc and bcc fields are parenthesized lists of address structures. An address structure is a parenthesized list that describes an electronic mail address. The fields of an address structure are in the following order: personal name, [SMTP] at-domain-list (source route), mailbox name and host name. For instance, (("RSmith" NIL "RSmith" "test")).

(From [RFC-822]) Group syntax is indicated by a special form of address structure where the host name field is NIL. If the mailbox name field is also NIL, this is an end-of-group marker (semi-colon in RFC 822 syntax). If the mailbox name field is non-NIL, this is the start-of-group marker and the mailbox name field holds the group name phrase.

A field of an envelope or address structure that is not applicable is presented as NIL. Note that the server MUST default the reply-to and sender fields from the "from" field; the client is not expected to know how to do this.

• BODY

Returns the same information as BODYSTRUCTURE except for the Extension data (see BODYSTRUCTURE) which is not returned.

Example:

   msgDataItem:="BODY"
   $Err:=IMAP_MsgFetch(imap_ID;1;msgDataItem;msgDataItemValue)

msgDataItem returns BODY ("TEXT" "PLAIN" ("CHARSET" "us-ascii") NIL NIL "8BIT" 8 1)

• BODYSTRUCTURE

Retrieves the MIME body structure of the message. The server computes this by parsing the MIME header fields in the message header and MIME headers in the body part. This data item is especially useful for scanning a message content without downloading it. For instance, you can quickly check the size of each part or just check the attachment file names. BODYSTRUCTURE returns a parenthesized list including the parenthesized list, quoted strings and unquoted strings.

Depending on the message content, BODYSTRUCTURE will return either a "non- multipart" parenthesized list or a nested one ("multipart" parenthesized list):

• "non-multipart" parenthesized list: this is, for instance, similar to non-multipart e-mail; a simple text message of 48 lines and 2279 bytes can have a body structure of: ("TEXT" "PLAIN" ("CHARSET" "us-ascii") NIL NIL "8BIT" 8 1 NIL NIL NIL).

The basic fields of a "non-multipart" parenthesized list are in the following order:

body type	A string giving the content media type name
	(Content-type: media type e.g. TEXT)
body subtype	A string giving the content subtype name
	(Content-type: subtype e.g. PLAIN)
body parameter	A parenthesized list of attribute/value pairs
parenthesized list	[e.g. ("CHARSET" "US-ASCII" "NAME" "cc.diff")
	where "US-ASCII" is the value of "CHARSET" and
	"cc.diff" is the value of "NAME".
body id	A string giving the content id (allows one body to make a reference
	to another one). Accordingly, bodies may be labeled using the
	"Content-ID" header field. The Content-ID value has special
	semantics in the case of a multipart/alternative media type.
	This is explained in the section of RFC 2046 dealing with
	multipart/alternative cases.
body description	A string giving the content description
body encoding	A string giving the content transfer encoding
	(Content-Transfer-Encoding)
body size	A number giving the size of the body in bytes.
	Note that this is the size during transfer encoding
	and not the resulting size after decoding.

- A body of the MESSAGE type and RFC822 subtype contains, immediately following the basic fields, the envelope structure, body structure, and size in text lines of the encapsulated message.

- A body of the TEXT type contains, immediately following the basic fields, the size of the body in text lines. Note that this is the size during content transfer encoding and not the resulting size after decoding.

Extension data follows the basic fields and type-specific fields listed above. Extension data is never returned with the BODY fetch, but can be returned with a BODYSTRUCTURE fetch.

Extension data , if present, of a "non multipart" parenthesized list MUST be in the defined order:

body MD5	A string giving the body MD5 value as defined in [MD5]
body disposition	A parenthesized list consisting of a disposition type string
	followed by a parenthesized list of disposition attribute/value pairs
	as defined in [DISPOSITION]
body language	A string or parenthesized list giving the body language value
	as defined in [LANGUAGE-TAGS]

Any extension data which follows are not yet defined in this version of the protocol and will be as described above under multipart extension data.

Example:

Description:

• "multipart" parenthesized list: this is the case of multipart e-mail; it includes a "non-multipart" parenthesized list.

Parenthesis nesting indicates multiple parts. The first element of the parenthesized list is a nested body instead of a body type. The second element of the parenthesized list is the multipart subtype (mixed, digest, parallel, alternative, etc.).

The multipart subtype is followed by the Extension data. Extension data, if present, MUST be in the defined order:

body parameter	A parenthesized list of attribute/value pairs
parenthesized list
body disposition	A parenthesized list consisting of a disposition type string
	followed by a parenthesized list of disposition attribute/value pairs
	as defined in [DISPOSITION]
body language	A string or parenthesized list giving the body language value
	as defined in [LANGUAGE-TAGS]

Any extension data which follows are not yet defined in this version of the protocol. This extension data can consist of zero or more NILs, strings, numbers or potentially nested parenthesized lists of such data. Client implementations that do a BODYSTRUCTURE fetch MUST be prepared to accept such extension data. Server implementations MUST NOT send such extension data until it has been defined by a revision of this protocol.

Example:

Description:

• UID

Retrieves a number expressing the message unique identifier of the message. This is equivalent to executing the IMAP_UIDToMsgNum.

Since this number is returned into a text area, you will have to convert it into a Long integer.

Example:

   msgDataItem:="UID"
   $Err:=IMAP_MsgFetch(imap_ID;1;msgDataItem;msgDataItemValue)

msgDataItemValue returns UID 250000186

To retrieve a longint value:

   C_LONGINT(vLongint)
   VLongint:=Num("250000186")

• FAST

Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE)

Example:

   $Err:=IMAP_MsgFetch (imap_ID; msgNum;"FAST";msgDataItemValue)

msgDataItemValue returns "FLAGS (\Seen \Answered) INTERNALDATE "17-Jul-2001 15:45:37 +0200" RFC822.SIZE 99599"

• ALL

Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE)

• FULL

Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODY)

IMAP_SetFlags, IMAP_UIDToMsgNum.