4D Doc Center : IMAP

Home

4D Internet Commands v14

IMAP_SetFlags


IMAP_SetFlags ( imap_ID ; startMsg ; endMsg ; msgFlagsList ; deleteOption ) -> Function result

Parameter	Type	Description
imap_ID	Longint	Reference to an IMAP login
startMsg	Longint	Start message number
endMsg	Longint	End message number
msgFlagsList	String	Flag values to add or remove
deleteOption	Integer	1 = add flag value, 0 = remove flag value
Function result	Integer	Error code

Description

The IMAP_SetFlags command allows adding or clearing of several flags at a time, attached to the specified range of messages.

IMAP protocol allows associating of a list of flags with a message. There are two types of flags: permanent or session-only.
Permanent flags are added or removed permanently from the message flags (see IMAP_SetCurrentMB); in other words, subsequent sessions will reflect any changes in permanent flags.
Changes made for session flags are only valid for that session.

The currently defined system flags are:

Seen: Message has been read.
Answered: Message has been answered.
Flagged: Message is “flagged” for urgent/special attention.
Deleted: Message is “deleted” for later removal with IMAP_Delete, IMAP_CloseCurrentMB, IMAP_SetCurrentMB or IMAP_Logout.
Draft: Message is in draft format; in other words, not complete.
Recent: Message “recently” arrived in this mailbox. This session is the first session notified about this message; subsequent sessions will not see the \Recent flag set for this message. This permanent flag is managed by the IMAP server and cannot be modified by an IMAP client using IMAP_SetFlags, for instance.

An IMAP server may allow a client to define new “flags” or, on another IMAP server, may allow managing of flags other than those previously indicated. This depends on the IMAP server implementation. In this case, these special flags are called “keywords” and do not begin with “\” (see IMAP_SetCurrentMB).

Note: If you set the \Deleted flag and close the current session by executing IMAP_SetCurrentMB, IMAP_CloseCurrentMB, IMAP_Delete or IMAP_Logout, the message will be “deleted” permanently.

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

startMsg is a long integer number that specifies the starting message number of the message range to be examined. The message number is a value representing the position of a message within the list of all messages in the current working mailbox.

endMsg is a long integer number that specifies the ending message number of the message range to be examined. The message number is a value representing the position of a message within the list of all messages in the current working mailbox.

Note: The IMAP_Delete, IMAP_MsgLstInfo, IMAP_MsgLst, IMAP_SetFlags, IMAP_GetFlags and IMAP_CopyToMB commands do not return an error if the startMsg is greater than the endMsg. In the event that this occurs, the command – in effect – does nothing.

msgFlagsList may contain one or several flags. In the case of several flags, the string must be a list of flags, separated by spaces. See examples below.

Only flags listed as permanentFlags, (see IMAP_SetCurrentMB), will be applied.

deleteOption is an integer value which specifies whether to remove or add the flag(s) specified by the msgFlagsList parameter:

A value of zero will remove the flag(s) specified in msgFlagsList.
A value of 1 will add the flag(s) specified in msgFlagsList.

Example 1

Set the \Answered and \Draft flags for the messages specified by startMsg and endMsg whether these flags were set previously or not:

 msgFlagsName:="\Answered \Draft"

  ` \Answered and \Draft are separated by a space (ASCII code)

 IMAP_SetFlags(imap_ID;startMsg;endMsg;msgFlagsName;1)

Example 2

Remove the \Deleted flag for the messages specified by startMsg and endMsg whether this flag was set previously or not:

 msgFlagsName:="\Deleted"

 IMAP_SetFlags(imap_ID;startMsg;endMsg;msgFlagsName;0)

Example 3

Set the \Deleted flag for the messages specified by startMsg and endMsg whether this flag was set previously or not:

 msgFlagsName:="\Deleted"

 IMAP_SetFlags(imap_ID;startMsg;endMsg;msgFlagsName;1)

 IMAP_CloseCurrentMB(imap_ID)

  `Closes the current mailbox and permanently deletes the specified messages.

Example 4

Set the \Answered flag depending on the CheckBoxAnswered value:

$Error:=IMAP_SetFlags(vImap_ID;$msgNum;$msgNum;"\Answered";Num(CheckBoxAnswered=0))