Get-SMIMEIMAP Cmdlet

Parameters   Output Objects   Config Settings  

The Get-SMIMEIMAP component is used to retrieve electronic mail from Internet Message Access (IMAP) servers.

Syntax

Get-SMIMEIMAP [parameters]

Remarks

This cmdlet is the SMIME enabled equivalent of GETIMAP. In addition to implementing a standard Internet Message Access Protocol (IMAP) client as specified in RFC 1730 and RFC 2060 for retrieving email and listing mail folders (mailboxes), the cmdlet can decrypt and/or verify SMIME email messages.

To use the cmdlet to retrieve email, you must specify a mail Server, User, and Password. Specify the Folder for the mailbox you wish to connect to. The email message (or range of messages) to download is given by View.

Retrieved email messages will be returned in one or more EmailMessages. Brief information (Id, From, Subject, and size) about each retrieved email will be returned in one or more MessageHeaderss.

You may also list all of your mailboxes by setting the ListFolders switch. Folders will be returned in one or more MailBoxObjects.

# get a list of the mailboxes get-imap -server mailserver -credential $cred -listfolders # list the last 5 messages to arrive from the default mailbox (INBOX) get-imap -server mailserver -credential $cred -list 5 # view message number 8320 in the "Archive" mailbox get-imap -server mailserver -credential $cred -folder "INBOX.Archive" -view 8320

Connection Handling

This cmdlet supports persistent connections through the Connection parameter. To establish a new SMIMEIMAP connection, use the Connect-SMIMEIMAP cmdlet. To close the connection, use the Disconnect-SMIMEIMAP 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	Indicates whether or not to list the mailbox ACLs.
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 decryption certificate.
CertStoreType	The type of certificate store for the decryption certificate.
CertSubject	The subject of the certificate used for decryption.
Config	Specifies one or more configuration settings.
Credential	The PSCredential object to use for user/password authentication.
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.
HeadersOnly	If true, only message headers will be fetched.
List	Number of messages to list.
ListFolders	Indicates whether or not to perform a List Mailboxes operation on the IMAP server.
LocalFile	Part is stored here if this property is set.
LocalIP	The IP address of the local interface to use.
LogFile	The location of a file to which debug information is written.
Part	If set, the component will retrieve the content of the part from the server.
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.
SignerCertPassword	The password to the certificate store.
SignerCertStore	The name of the certificate store for the signature verification certificate.
SignerCertStoreType	The type of certificate store for the signature verification certificate. In most cases PublicKeyFile is used.
SignerCertSubject	The subject of the recipient's public certificate used for signature verification.
SMIME	Specifies the expected protection level on the received messages.
Timeout	The maximum time allowed for the operation.
User	The username to use for authentication.
View	The message number to view.

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.

SMIMEIMAPEmailMessage	Object containing the entire text of the email message.

Config Settings

---

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

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 (Get-SMIMEIMAP Cmdlet)

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

Syntax

Get-SMIMEIMAP -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 (Get-SMIMEIMAP Cmdlet)

An existing SMIMEIMAP connection.

Syntax

Get-SMIMEIMAP -Connection SMIMEIMAPConnection

Remarks

Represents an existing, persistent SMIMEIMAP 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-SMIMEIMAP cmdlet and closed using the Disconnect-SMIMEIMAP cmdlet.

Default Value

null

ACL Property (Get-SMIMEIMAP Cmdlet)

Indicates whether or not to list the mailbox ACLs.

Syntax

Get-SMIMEIMAP -ACL SwitchParameter

Remarks

Mailbox rights are provided through one or more ACL objects. Standard rights include:

Default Value

false

AuthMechanism Property (Get-SMIMEIMAP Cmdlet)

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

Syntax

Get-SMIMEIMAP -AuthMechanism string

Remarks

The applicable values are the following:

Default Value

0

CertPassword Property (Get-SMIMEIMAP Cmdlet)

The password to the certificate store.

Syntax

Get-SMIMEIMAP -CertPassword string

Remarks

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

Default Value

""

Parameter Alias

CertificatePassword

CertStore Property (Get-SMIMEIMAP Cmdlet)

The name of the certificate store for the decryption certificate.

Syntax

Get-SMIMEIMAP -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 the certificate used for decryption. If CertStore has a value, and CertSubject has been set, a search for a certificate is initiated during processing. 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"

CertStoreType Property (Get-SMIMEIMAP Cmdlet)

The type of certificate store for the decryption certificate.

Syntax

Get-SMIMEIMAP -CertStoreType string

Remarks

This parameter can take one of the following values:

Default Value

0

CertSubject Property (Get-SMIMEIMAP Cmdlet)

The subject of the certificate used for decryption.

Syntax

Get-SMIMEIMAP -CertSubject string

Remarks

During the decryption phase of processing, 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 decrypt the incoming message.

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 (Get-SMIMEIMAP Cmdlet)

Specifies one or more configuration settings.

Syntax

Get-SMIMEIMAP -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

Credential Property (Get-SMIMEIMAP Cmdlet)

The PSCredential object to use for user/password authentication.

Syntax

Get-SMIMEIMAP -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

FirewallHost Property (Get-SMIMEIMAP Cmdlet)

Name or IP address of firewall.

Syntax

Get-SMIMEIMAP -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 (Get-SMIMEIMAP Cmdlet)

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

Syntax

Get-SMIMEIMAP -FirewallPassword string

Remarks

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

Default Value

""

FirewallPort Property (Get-SMIMEIMAP Cmdlet)

The port of the firewall to which to connect.

Syntax

Get-SMIMEIMAP -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 (Get-SMIMEIMAP Cmdlet)

Determines the type of firewall to connect through.

Syntax

Get-SMIMEIMAP -FirewallType string

Remarks

The applicable values are the following:

Default Value

0

FirewallUser Property (Get-SMIMEIMAP Cmdlet)

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

Syntax

Get-SMIMEIMAP -FirewallUser string

Remarks

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

Default Value

""

Folder Property (Get-SMIMEIMAP Cmdlet)

The IMAP folder to which to connect.

Syntax

Get-SMIMEIMAP -Folder string

Remarks

Name of the mailbox selected on the IMAP Server.

Default Value

""

Parameter Alias

Mailbox

Force Property (Get-SMIMEIMAP Cmdlet)

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

Syntax

Get-SMIMEIMAP -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

HeadersOnly Property (Get-SMIMEIMAP Cmdlet)

If true, only message headers will be fetched.

Syntax

Get-SMIMEIMAP -HeadersOnly SwitchParameter

Remarks

If View is specified, HeadersOnly will control whether the entire message or only the headers are fetched.

Default Value

false

List Property (Get-SMIMEIMAP Cmdlet)

Number of messages to list.

Syntax

Get-SMIMEIMAP -List int

Remarks

List indicates the maximum number of messages to return, starting at the newest message.

Default Value

0

Parameter Alias

Last

ListFolders Property (Get-SMIMEIMAP Cmdlet)

Indicates whether or not to perform a List Mailboxes operation on the IMAP server.

Syntax

Get-SMIMEIMAP -ListFolders SwitchParameter

Remarks

If ListFolders is set, all the mailboxes under Folder on the IMAP server will be listed. If Folder is not set explicitly then all mailboxes on the server are listed.

Default Value

false

Parameter Alias

ListMailboxes

LocalFile Property (Get-SMIMEIMAP Cmdlet)

Part is stored here if this property is set.

Syntax

Get-SMIMEIMAP -LocalFile string

Remarks

If this property is not set, the output object contains the message part content.

Default Value

""

LocalIP Property (Get-SMIMEIMAP Cmdlet)

The IP address of the local interface to use.

Syntax

Get-SMIMEIMAP -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 (Get-SMIMEIMAP Cmdlet)

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

Syntax

Get-SMIMEIMAP -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

""

Part Property (Get-SMIMEIMAP Cmdlet)

If set, the component will retrieve the content of the part from the server.

Syntax

Get-SMIMEIMAP -Part string

Remarks

If LocalFile is set, the part content is written to file.

Default Value

""

Password Property (Get-SMIMEIMAP Cmdlet)

The password to use for authentication.

Syntax

Get-SMIMEIMAP -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 (Get-SMIMEIMAP Cmdlet)

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

Syntax

Get-SMIMEIMAP -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 (Get-SMIMEIMAP Cmdlet)

The address of the Server.

Syntax

Get-SMIMEIMAP -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.

SignerCertPassword Property (Get-SMIMEIMAP Cmdlet)

The password to the certificate store.

Syntax

Get-SMIMEIMAP -SignerCertPassword string

Remarks

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

Default Value

""

SignerCertStore Property (Get-SMIMEIMAP Cmdlet)

The name of the certificate store for the signature verification certificate.

Syntax

Get-SMIMEIMAP -SignerCertStore 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 the certificate used for signature verification. If CertStore has a value, and CertSubject has been set, a search for a certificate is initiated during processing. 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"

SignerCertStoreType Property (Get-SMIMEIMAP Cmdlet)

The type of certificate store for the signature verification certificate. In most cases PublicKeyFile is used.

Syntax

Get-SMIMEIMAP -SignerCertStoreType string

Remarks

This parameter can take one of the following values:

Default Value

0

SignerCertSubject Property (Get-SMIMEIMAP Cmdlet)

The subject of the recipient's public certificate used for signature verification.

Syntax

Get-SMIMEIMAP -SignerCertSubject string

Remarks

During the signature verification phase of processing, the cmdlet will search the store specified in CertStore for a certificate that matches this parameter. If the store contains a match, it is used to verify the signature of the incoming message.

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

"*"

SMIME Property (Get-SMIMEIMAP Cmdlet)

Specifies the expected protection level on the received messages.

Syntax

Get-SMIMEIMAP -SMIME string

Remarks

This parameter specifies the expected protection level of received message. The cmdlet uses this value to determine what operations are performed on the message. Possible values are:

Default Value

0

Timeout Property (Get-SMIMEIMAP Cmdlet)

The maximum time allowed for the operation.

Syntax

Get-SMIMEIMAP -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

User Property (Get-SMIMEIMAP Cmdlet)

The username to use for authentication.

Syntax

Get-SMIMEIMAP -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

""

View Property (Get-SMIMEIMAP Cmdlet)

The message number to view.

Syntax

Get-SMIMEIMAP -View int

Remarks

View indicates which message to return. Upon successful retrieval of the message, a SMIMEIMAPEmailMessage object is returned by the cmdlet.

Default Value

0

Parameter Alias

MessageNumber

SMIMEIMAPEmailMessage Output Object (Get-SMIMEIMAP Cmdlet)

Object containing the entire text of the email message.

Syntax

Object SMIMEIMAPEmailMessage {
   string Headers;
   string Text;
   string From;
   string FromFriendlyName;
   string FromEmail;
   string To;
   string CC;
   string Subject;
   string Date;
   long Size;
   string Flags;
   int PartCount;
   string[] PartId;
   string[] PartSize;
   string[] PartContentEncoding;
   string[] PartContentType;
   string[] PartFileName;
   string[] PartMultiPartMode;
   string[] PartParameters;
   bool MessageEncrypted;
   bool MessageSigned;
}

Remarks

When retrieving email messages, the result from the mail Server will be stored in one or more MessageHeaders and EmailMessage objects. The MessageHeaders will contain brief information, such as who the message is from, the subject of the message, and the message Id and size. However, this Object will also contain the full message body in the Text property.

The MessageEncrypted and MessageSigned properties will indicate if the message is encrypted or signed. Note that MessageEncrypted and MessageSigned will only be set when View is set.

Config Settings (Get-SMIMEIMAP 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.

Base Config Settings