Set-IMAP Cmdlet

Parameters   Output Objects   Config Settings  

The Set-IMAP component is used to manage the mail on your Internet Message Access (IMAP) server.

Syntax

Set-IMAP [parameters]

Remarks

This cmdlet implements a standard Internet Message Access (IMAP) client as specified in RFC 1730 and RFC 2060 for deleting messages and managing mail folders.

The use the cmdlet you must specify a mail Server, User, and Password.

To create folders, use Create.

To establish a secure SSL connection, set the SSL parameter.

This cmdlet handles deleting email messages and managing IMAP mail folders. To send an email, see the SEND-EMAIL cmdlet. To retrieve messages or list IMAP mail folders, use the GET-IMAP cmdlet.

The cmdlets support pipeline input for some of their parameters. Prebuilding an object and piping it to the cmdlet is very useful, but should be used with caution to prevent security conflicts. Steps have been taken to decrease the risk of a possibly accidental pipe to the cmdlet, for instance, the Credential parameter cannot be piped to the cmdlet and must be specified manually.

# create a new folder set-imap -server myserver -cred $mycred -folder Inbox.NewFolder -create # set flags of a message set-imap -server myserver -cred $mycred -message 205554 -flags "\Draft"

Connection Handling

This cmdlet supports persistent connections through the Connection parameter. To establish a new IMAP connection, use the Connect-IMAP cmdlet. To close the connection, use the Disconnect-IMAP cmdlet.

Parameter List

---

The following is the full list of the parameters of the cmdlet with short descriptions. Click on the links for further details.

Connection	An already established connection.
LogFile	The location of a file to which debug information is written.
ACL	Sets mailbox access control rights for a specific user.
ACLUser	The user for which to change the ACL on Folder for the new values specified by ACL .
AddFlags	Adds the flags to the message specified by Message .
AuthMechanism	The authentication mechanism to be used when connecting to the mail server.
CertPassword	The password to the certificate store.
CertStore	The name of the certificate store for the client certificate.
CertStoreType	The type of certificate store for the client certificate.
CertSubject	The subject of the certificate used for client authentication.
Config	Specifies one or more configuration settings.
Create	Creates a mailbox.
Credential	The PSCredential object to use for user/password authentication.
Expunge	Whether to expunge the mailbox after setting message flags.
FirewallHost	Name or IP address of firewall.
FirewallPassword	A password if authentication is to be used when connecting through the firewall.
FirewallPort	The port of the firewall to which to connect.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
Folder	The IMAP folder to which to connect.
Force	Forces the component to accept the default behavior instead of querying the user.
LocalIP	The IP address of the local interface to use.
LogFile	The location of a file to which debug information is written.
Message	Indicates the message that the component will operate on.
Password	The password to use for authentication.
Port	The TCP port in the remote host to which to connect.
Server	The address of the Server.
SetFlags	Resets the flags to the message specified by Message with the flags specified by SetFlags .
SetLabels	Specifies Gmail labels to be set on the message.
SSL	Determines how the component starts SSL negotiation.
SSLAccept	The encoded public key of the certificate which is to be trusted explicitly.
Subscribe	Subscribe to the mailbox specified by rpFolder;.
Timeout	The maximum time allowed for the operation.
Unsubscribe	Unsubscribe from the mailbox specified by rpFolder;.
User	The username to use for authentication.

Output Objects

---

The following is the full list of the output objects returned by the cmdlet with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the cmdlet with short descriptions. Click on the links for further details.

MessageCount	Number of messages in the mailbox.
AlwaysReturnUIDs	Instructs the server to return UIDs even if not in UIDMode.
AppendToMailboxDateTime	Specifies the date-time parameter used in the initial APPEND request.
AuthorizationIdentity	The value to use as the authorization identity when SASL authentication is used.
AutoDecodeSubject	Instructs the component to automatically decode message subjects.
AutoDecodeText	Whether to decode MessageText when AutoDecodeParts is True.
FetchAfterSearch	Determines if messages matching the SearchCriteria are fetched after calling SearchMailbox.
FetchTextAndHeaders	Specifies whether the message body and headers are fetched in a single request.
IncludeHeaders	Instructs the component to include the headers in the LocalFile.
MaskSensitive	Whether sensitive properties should be masked when logging.
SendIDCommand	Instructs component to send the ID command if the server advertises support for it.
UTF7MailboxNames	Specifies whether or not to automatically encode and decode UTF-7 mailbox names.
ConnectionTimeout	Sets a separate timeout value for establishing a connection.
FirewallAutoDetect	Tells the component whether or not to automatically detect and use firewall system settings, if available.
FirewallHost	Name or IP address of firewall (optional).
FirewallPassword	Password to be used if authentication is to be used when connecting through the firewall.
FirewallPort	The TCP port for the FirewallHost;.
FirewallType	Determines the type of firewall to connect through.
FirewallUser	A user name if authentication is to be used connecting through a firewall.
KeepAliveInterval	The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveTime	The inactivity time in milliseconds before a TCP keep-alive packet is sent.
Linger	When set to True, connections are terminated gracefully.
LingerTime	Time in seconds to have the connection linger.
LocalHost	The name of the local host through which connections are initiated or accepted.
LocalPort	The port in the local host where the component binds.
MaxLineLength	The maximum amount of data to accumulate when no EOL is found.
MaxTransferRate	The transfer rate limit in bytes per second.
ProxyExceptionsList	A semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAlive	Determines whether or not the keep alive socket option is enabled.
TcpNoDelay	Whether or not to delay when sending packets.
UseIPv6	Whether to use IPv6.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallData	Used to send extra data to the firewall.
InBufferSize	The size in bytes of the incoming queue of the socket.
OutBufferSize	The size in bytes of the outgoing queue of the socket.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
MaskSensitive	Whether sensitive data is masked in log messages.
UseInternalSecurityAPI	Tells the component whether or not to use the system security libraries or an internal implementation.

LogFile Parameter (Set-IMAP Cmdlet)

The location of a file to which debug information is written.

Syntax

Set-IMAP -LogFile string

Remarks

When specified, the cmdlet will log debug information to the file. If the file exists, the information will be appended.

Default Value

null

Connection Parameter (Set-IMAP Cmdlet)

An existing IMAP connection.

Syntax

Set-IMAP -Connection IMAPConnection

Remarks

Represents an existing, persistent IMAP connection to be used. After this cmdlet executes, the connection will remain opened to be used in an another call. New connections can be established using the Connect-IMAP cmdlet and closed using the Disconnect-IMAP cmdlet.

Default Value

null

ACL Property (Set-IMAP Cmdlet)

Sets mailbox access control rights for a specific user.

Syntax

Set-IMAP -ACL string

Remarks

Changes the access control list for the mailbox specified in the Folder property so that ACLUser is granted the permissions specified.

ACL is a string containing an optional plus ("+") or minus ("-") prefix, followed by zero or more rights characters. If the string starts with a plus, the rights are added to any existing rights for the identifier. If the string starts with a minus, the rights are removed from any existing rights for the identifier. If the string does not start with a plus or minus, the rights replace any existing rights for the identifier.

Standard rights include:

Default Value

""

ACLUser Property (Set-IMAP Cmdlet)

The user for which to change the ACL on Folder for the new values specified by ACL .

Syntax

Set-IMAP -ACLUser string

Remarks

If this parameter is not set by ACL is then an error is thrown by the cmdlet.

Default Value

""

AddFlags Property (Set-IMAP Cmdlet)

Adds the flags to the message specified by Message .

Syntax

Set-IMAP -AddFlags string

Remarks

Examples of possible flag values are server dependent, but can include:

Default Value

""

Parameter Alias

AppendFlags

AuthMechanism Property (Set-IMAP Cmdlet)

The authentication mechanism to be used when connecting to the mail server.

Syntax

Set-IMAP -AuthMechanism string

Remarks

The applicable values are the following:

Default Value

0

CertPassword Property (Set-IMAP Cmdlet)

The password to the certificate store.

Syntax

Set-IMAP -CertPassword string

Remarks

Specifies a password (if required) to access the specified certificate store.

Default Value

""

Parameter Alias

CertificatePassword

CertStore Property (Set-IMAP Cmdlet)

The name of the certificate store for the client certificate.

Syntax

Set-IMAP -CertStore string

Remarks

The CertStoreType parameter specifies the type of the certificate store specified by CertStore. If the store is password protected, specify the password in CertPassword.

CertStore is used in conjunction with the CertSubject parameter in order to specify client certificates. If CertStore has a value, and CertSubject has been set, a search for a certificate is initiated during logon. Please refer to the CertSubject parameter for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this parameter must be set to the name of the file.

Default Value

"MY"

Parameter Alias

CertificateStore

CertStoreType Property (Set-IMAP Cmdlet)

The type of certificate store for the client certificate.

Syntax

Set-IMAP -CertStoreType string

Remarks

This parameter can take one of the following values:

Default Value

0

CertSubject Property (Set-IMAP Cmdlet)

The subject of the certificate used for client authentication.

Syntax

Set-IMAP -CertSubject string

Remarks

During the user authentication phase of the logon process, the cmdlet will search the store specified in CertStore for a certificate that matches this parameter. If the store contains a private key for that certificate, it is used to verify the user's identity with the secure server.

When this parameter is set, a search is performed in the current certificate store certificate with matching subject.

If an exact match is not found, the store is searched for subjects containing the value of the parameter.

When setting the parameter to a partial subject, CN= should be omitted. For example, the following code would find the certificate with subject CN=Test Certificate, OU=People, C=US

Example (Searching with partial subject)

-certsubject "Test"

If a match is not found, the parameter is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

Default Value

"*"

Config Property (Set-IMAP Cmdlet)

Specifies one or more configuration settings.

Syntax

Set-IMAP -Config string[]

Remarks

The Config parameter takes one or more name-value pairs that represent the name of the configuration setting and value, i.e.: -config "Name=Value"

Default Value

null

Create Property (Set-IMAP Cmdlet)

Creates a mailbox.

Syntax

Set-IMAP -Create SwitchParameter

Remarks

When setting the Create flag, the folder specified by Folder will be created.

Default Value

false

Parameter Alias

CreateFolder

Credential Property (Set-IMAP Cmdlet)

The PSCredential object to use for user/password authentication.

Syntax

Set-IMAP -Credential PSCredential

Remarks

Every cmdlet that supports user authentication will expose a Credential parameter. A PSCredential object should be specified for this parameter. Alternatively, the User and Password parameters can be set to represent the credential information.

If the cmdlet supports client key authentication it uses the password field of this object for the certificate's password. This setting is enabled by using public key authentication. Note: Due to security reasons, it is recommended that you use the Credential parameter rather than User and Password to specify the authentication information.

Default Value

null

Parameter Position

1

Parameter Alias

auth

Expunge Property (Set-IMAP Cmdlet)

Whether to expunge the mailbox after setting message flags.

Syntax

Set-IMAP -Expunge SwitchParameter

Remarks

Permanently remove all messages that have the 'Deleted' flag set from the current Folder.

Default Value

false

FirewallHost Property (Set-IMAP Cmdlet)

Name or IP address of firewall.

Syntax

Set-IMAP -FirewallHost string

Remarks

If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost parameter is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost parameter is set to the corresponding address. If the search is not successful, an error is returned.

Default Value

""

FirewallPassword Property (Set-IMAP Cmdlet)

A password if authentication is to be used when connecting through the firewall.

Syntax

Set-IMAP -FirewallPassword string

Remarks

If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to authenticate against the firewall.

Default Value

""

FirewallPort Property (Set-IMAP Cmdlet)

The port of the firewall to which to connect.

Syntax

Set-IMAP -FirewallPort int

Remarks

The TCP port for the FirewallHost. See the description of the FirewallHost parameter for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType parameter for details. Setting this parameter will overwrite the default settings for the firewall port as specified by FirewallType.

Default Value

0

FirewallType Property (Set-IMAP Cmdlet)

Determines the type of firewall to connect through.

Syntax

Set-IMAP -FirewallType string

Remarks

The applicable values are the following:

Default Value

0

FirewallUser Property (Set-IMAP Cmdlet)

A user name if authentication is to be used connecting through a firewall.

Syntax

Set-IMAP -FirewallUser string

Remarks

If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to authenticate against the firewall.

Default Value

""

Folder Property (Set-IMAP Cmdlet)

The IMAP folder to which to connect.

Syntax

Set-IMAP -Folder string

Remarks

Name of the mailbox selected on the IMAP Server.

Default Value

""

Parameter Alias

Mailbox

Force Property (Set-IMAP Cmdlet)

Forces the component to accept the default behavior instead of querying the user.

Syntax

Set-IMAP -Force SwitchParameter

Remarks

The Force parameter is especially useful in a script environment where user interaction is not an option. Certain cmdlets that are SSH and SSL based will query the user if the security credentials of the certificate presented by the server are not met. Setting this parameter will force the cmdlet to accept the certificate of the server unconditionally.

Default Value

false

LocalIP Property (Set-IMAP Cmdlet)

The IP address of the local interface to use.

Syntax

Set-IMAP -LocalIP string

Remarks

This parameter is useful when the cmdlet is running on a machine that has more than one network interface (each with its own IP address and network access privileges).

Default Value

""

Parameter Alias

LocalAddress

LogFile Property (Set-IMAP Cmdlet)

The location of a file to which debug information is written.

Syntax

Set-IMAP -LogFile string

Remarks

When specified, the cmdlet will log debug information to the file. If the file exists, the information will be appended.

Default Value

""

Message Property (Set-IMAP Cmdlet)

Indicates the message that the component will operate on.

Syntax

Set-IMAP -Message int

Remarks

If flags need to be added to a certain message, this parameter will specify the message number.

Default Value

0

Password Property (Set-IMAP Cmdlet)

The password to use for authentication.

Syntax

Set-IMAP -Password string

Remarks

Every time User, or Password are set, the cmdlet will authenticate with the server. It is recommended that the Credential parameter is set instead of User/Password because of security reasons. If both Credential and this parameter is set, the Credential value is used.

Default Value

""

Port Property (Set-IMAP Cmdlet)

The TCP port in the remote host to which to connect.

Syntax

Set-IMAP -Port int

Remarks

Port specifies a service port on the remote host to which to connect.

A valid port number (a value between 1 and 65535) is required for the connection to take place.

Default Value

143

Server Property (Set-IMAP Cmdlet)

The address of the Server.

Syntax

Set-IMAP -Server string

Remarks

The cmdlet requires a server address to be provided. Either an IP address or the server host name can be provided.

Default Value

""

Parameter Position

0

This is a required parameter.

SetFlags Property (Set-IMAP Cmdlet)

Resets the flags to the message specified by Message with the flags specified by SetFlags .

Syntax

Set-IMAP -SetFlags string

Remarks

Both the SetFlags and AddFlags parameters can be used to manage the flags of the message. When using SetFlags the original flags of the message are not preserved and only the flags specified by the parameter are applied to the message. AddFlags is used to append flags to the current message.

Default Value

""

Parameter Alias

Flags

SetLabels Property (Set-IMAP Cmdlet)

Specifies Gmail labels to be set on the message.

Syntax

Set-IMAP -SetLabels string

Remarks

This parameter optionally specifies a space separated list of Gmail labels to be set for the message specified by Message. When the label to be set includes a space it must be surrounded by quotes. For instance the command below sets the labels testlabel1 and test label2.

Set-IMAP -ssl implicit -Server imap.gmail.com -Port 993 -Message 109575 -User me@gmail.com -Password mypassword -Labels "testlabel1 `"test label2`""

Note: This setting is only applicable when connected to a Gmail account.

Default Value

""

Parameter Alias

Labels

SSL Property (Set-IMAP Cmdlet)

Determines how the component starts SSL negotiation.

Syntax

Set-IMAP -SSL string

Remarks

SSL may have one of the following values:

Default Value

3

SSLAccept Property (Set-IMAP Cmdlet)

The encoded public key of the certificate which is to be trusted explicitly.

Syntax

Set-IMAP -SSLAccept string

Remarks

Ordinarily, the certificate presented by the server will be checked against the system certificate stores to see if the Certificate Authority is trusted, and if not, the cmdlet will prompt the user to accept the certificate. Setting this parameter will override the system settings and trust the certificate provided.

After each connection, regardless of whether or not the certificate was trusted, the cmdlet will store the certificate presented by the server in the $SSLServerCertificate session variable. This variable can be inspected to view details of the server's certificate.

If the Force parameter is set, the cmdlet will accept the server's certificate unconditionally.

In cases where the certificate presented by the server is not trusted, a prompt will be shown to the user. This prompt will allow the user to decide whether or not they would like to accept the certificate presented by the server.

There may be cases where you do not want a prompt to be displayed or would like to handle the response supplied directly within your script. This can be done by setting the $SSLAcceptPreference variable prior to running the cmdlet. The available values for this variable are:

Default Value

""

Parameter Alias

Accept

Subscribe Property (Set-IMAP Cmdlet)

Subscribe to the mailbox specified by rpFolder;.

Syntax

Set-IMAP -Subscribe SwitchParameter

Remarks

If this flag is set, the cmdlet will subscribe to the mailbox specified by the Folder parameter.

Default Value

false

Timeout Property (Set-IMAP Cmdlet)

The maximum time allowed for the operation.

Syntax

Set-IMAP -Timeout int

Remarks

After the specified interval in seconds, the cmdlet will throw a Timeout error if the operation is not completed.

Default Value

10

Unsubscribe Property (Set-IMAP Cmdlet)

Unsubscribe from the mailbox specified by rpFolder;.

Syntax

Set-IMAP -Unsubscribe SwitchParameter

Remarks

If this flag is set, the cmdlet will unsubscribe from the mailbox specified by the Folder parameter.

Default Value

false

User Property (Set-IMAP Cmdlet)

The username to use for authentication.

Syntax

Set-IMAP -User string

Remarks

Every time User and Password are set, the cmdlet will authenticate with the server. It is recommended that the Credential parameter is set instead of User/Password because of security reasons. If both Credential and this parameter is set, the Credential value is used.

Default Value

""

Config Settings (Set-IMAP Cmdlet)

The cmdlet accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the cmdlet, access to these internal properties is provided through the Config method.

GetIMAP Config Settings

IMAP Config Settings

TCPClient Config Settings

Socket Config Settings

Base Config Settings