ExchangeClient Class

Namespace:
GemBox.Email.Exchange
Assembly:
GemBox.Email.dll

Represents a mail client that can be used for connecting to Exchange using the EWS protocol.

public class ExchangeClient
Public Class ExchangeClient
Inheritance:
System.Object
ExchangeClient

Constructors

ExchangeClient(String)

Initializes new instance of ExchangeClient.

public ExchangeClient(string host)
Public Sub New(host As String)
Parameters
host
System.String

The address of the server.

Properties

LogOutput

Gets or sets the log output writer.

public TextWriter LogOutput { get; set; }
Public Property LogOutput As TextWriter
Property Value
System.IO.TextWriter

The log output writer.

Remarks

Setting this property to a non-null value, enables communication logging. All commands and responses between the client and server will be written to the provided System.IO.TextWriter. Logging is disabled by setting this property to null.

Methods

Authenticate(String, String)

Authenticates the client with a specified user name and password.

public void Authenticate(string userName, string password)
Public Sub Authenticate(userName As String, password As String)
Parameters
userName
System.String

The user name.

password
System.String

The password for the user name.

Exceptions
System.InvalidOperationException

Client is already authenticated.

System.ArgumentException

Specified user name is null or Specified password is null.

Authenticate(String, String, ExchangeAuthentication)

Authenticates the client with specified user name, password or access token, and ExchangeAuthentication mechanism.

public void Authenticate(string userName, string passwordOrToken, ExchangeAuthentication authentication)
Public Sub Authenticate(userName As String, passwordOrToken As String, authentication As ExchangeAuthentication)
Parameters
userName
System.String

The user name.

passwordOrToken
System.String

The password or access token for the user name.

authentication
ExchangeAuthentication

A constant that specifies which authentication mechanism to use.

Exceptions
System.InvalidOperationException

Client is already authenticated.

System.ArgumentException

Specified user name is null or Specified password or access token is null.

CopyMessage(String, String)

Copies the specified message to another folder.

public void CopyMessage(string messageId, string destinationFolder)
Public Sub CopyMessage(messageId As String, destinationFolder As String)
Parameters
messageId
System.String

The message id.

destinationFolder
System.String

The destination folder name.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Destination folder is null or empty.

CreateFolder(String)

Creates folders based on full name.

For the input "Inbox/Parent/Child":
If there is already a "Parent" folder under the Inbox folder, a folder named "Child" will be created under that.
If there is no folder named "Parent" under the Inbox folder, first that one will be created, and then another folder named "Child" will be created under it.

public void CreateFolder(string name)
Public Sub CreateFolder(name As String)
Parameters
name
System.String

The full folder name.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty.

CreateFolder(String, DefaultFolders)

Creates a new sub folder with the specified name inside a default folder.

public void CreateFolder(string name, DefaultFolders parent)
Public Sub CreateFolder(name As String, parent As DefaultFolders)
Parameters
name
System.String

The full folder name.

parent
DefaultFolders

The parent default folder.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty.

CreateFolder(String, String)

Creates a new sub folder with the specified name inside a specific folder.

public void CreateFolder(string name, string parentId)
Public Sub CreateFolder(name As String, parentId As String)
Parameters
name
System.String

The folder name.

parentId
System.String

The Id of the parent folder.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty.

DeleteFolder(String, Boolean)

Deletes the specified folder.

public void DeleteFolder(string name, bool moveToDeletedItems)
Public Sub DeleteFolder(name As String, moveToDeletedItems As Boolean)
Parameters
name
System.String

The folder name.

moveToDeletedItems
System.Boolean

True if message should be moved to deleted items, false if it should be completely removed.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty or folder was not found.

DeleteFolderById(String, Boolean)

Deletes the specified folder.

public void DeleteFolderById(string id, bool moveToDeletedItems)
Public Sub DeleteFolderById(id As String, moveToDeletedItems As Boolean)
Parameters
id
System.String

The folder's id.

moveToDeletedItems
System.Boolean

True if message should be moved to deleted items, false if it should be completely removed.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder id is null or empty or folder was not found.

DeleteMessage(String, Boolean)

Deletes the specified message.

public void DeleteMessage(string exchangeMessageId, bool moveToDeletedItems)
Public Sub DeleteMessage(exchangeMessageId As String, moveToDeletedItems As Boolean)
Parameters
exchangeMessageId
System.String

The Exchange message id.

moveToDeletedItems
System.Boolean

True if message should be moved to deleted items, false if it should be completely removed.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Message id is null or empty.

GetFolderInfo(String)

Gets the info of a specified folder.

public ExchangeFolderInfo GetFolderInfo(string name)
Public Function GetFolderInfo(name As String) As ExchangeFolderInfo
Parameters
name
System.String

The full folder name.

Returns
ExchangeFolderInfo

The info of the specified folder.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty.

GetFolderInfoById(String)

Gets the info of a specified folder.

public ExchangeFolderInfo GetFolderInfoById(string id)
Public Function GetFolderInfoById(id As String) As ExchangeFolderInfo
Parameters
id
System.String

The folder's id.

Returns
ExchangeFolderInfo

The info of the specified folder.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder id is null or empty.

GetHeaders(String)

Gets the headers for the specified message.

public HeaderCollection GetHeaders(string exchangeMessageId)
Public Function GetHeaders(exchangeMessageId As String) As HeaderCollection
Parameters
exchangeMessageId
System.String

The Exchange message id.

Returns
HeaderCollection

A collection of message headers.

Exceptions
System.ArgumentException

Message id is null or empty.

GetMessage(String)

Finds a message with given id.

public MailMessage GetMessage(string exchangeMessageId)
Public Function GetMessage(exchangeMessageId As String) As MailMessage
Parameters
exchangeMessageId
System.String

The Exchange message id.

Returns
MailMessage

The found message.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Message id is null or empty.

FreeLimitReachedException

Free license limitation exceeded.

ImpersonateUser(String)

Defines an email to impersonate, allowing the client to perform operations on another user's mailbox.

public void ImpersonateUser(string email)
Public Sub ImpersonateUser(email As String)
Parameters
email
System.String

The email of the user to impersonate.

Remarks

Successfully using the impersonation requires the client to be authenticated using a token created with this permission.

ListFolders()

Lists all folders on the server.

public ReadOnlyCollection<ExchangeFolderInfo> ListFolders()
Public Function ListFolders As ReadOnlyCollection(Of ExchangeFolderInfo)
Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeFolderInfo>

A read-only collection of all folders on the server.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

ListFolders(DefaultFolders)

Lists sub folders of a default folder on the server.

public ReadOnlyCollection<ExchangeFolderInfo> ListFolders(DefaultFolders parent)
Public Function ListFolders(parent As DefaultFolders) As ReadOnlyCollection(Of ExchangeFolderInfo)
Parameters
parent
DefaultFolders

The parent default folder.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeFolderInfo>

A read-only collection of all folders on the server.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

ListFolders(DefaultFolders, Boolean)

Lists sub folders of a default folder on the server.

public ReadOnlyCollection<ExchangeFolderInfo> ListFolders(DefaultFolders parent, bool directChildrenOnly)
Public Function ListFolders(parent As DefaultFolders, directChildrenOnly As Boolean) As ReadOnlyCollection(Of ExchangeFolderInfo)
Parameters
parent
DefaultFolders

The parent default folder.

directChildrenOnly
System.Boolean

Whether or not to include only the parent's direct children (true) or to also include every child's sub folders recursively (false).

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeFolderInfo>

A read-only collection of all folders on the server.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

ListFolders(String)

Lists sub folders of a specific folder on the server.

public ReadOnlyCollection<ExchangeFolderInfo> ListFolders(string parentName)
Public Function ListFolders(parentName As String) As ReadOnlyCollection(Of ExchangeFolderInfo)
Parameters
parentName
System.String

The full name of the parent folder.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeFolderInfo>

A read-only collection of all folders on the server.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

ListFolders(String, Boolean)

Lists sub folders of a specific folder on the server.

public ReadOnlyCollection<ExchangeFolderInfo> ListFolders(string parentName, bool directChildrenOnly)
Public Function ListFolders(parentName As String, directChildrenOnly As Boolean) As ReadOnlyCollection(Of ExchangeFolderInfo)
Parameters
parentName
System.String

The full name of the parent folder.

directChildrenOnly
System.Boolean

Whether or not to include only the parent's direct children (true) or to also include every child's sub folders recursively (false).

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeFolderInfo>

A read-only collection of all folders on the server.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

ListFoldersById(String)

Lists sub folders of a specific folder on the server.

public ReadOnlyCollection<ExchangeFolderInfo> ListFoldersById(string parentId)
Public Function ListFoldersById(parentId As String) As ReadOnlyCollection(Of ExchangeFolderInfo)
Parameters
parentId
System.String

The id of the parent folder.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeFolderInfo>

A read-only collection of all folders on the server.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

ListFoldersById(String, Boolean)

Lists sub folders of a specific folder on the server.

public ReadOnlyCollection<ExchangeFolderInfo> ListFoldersById(string parentId, bool directChildrenOnly)
Public Function ListFoldersById(parentId As String, directChildrenOnly As Boolean) As ReadOnlyCollection(Of ExchangeFolderInfo)
Parameters
parentId
System.String

The id of the parent folder.

directChildrenOnly
System.Boolean

Whether or not to include only the parent's direct children (true) or to also include every child's sub folders recursively (false).

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeFolderInfo>

A read-only collection of all folders on the server.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

ListMessages(String)

Lists all messages in the selected folder.

public ReadOnlyCollection<ExchangeMessageInfo> ListMessages(string folderName)
Public Function ListMessages(folderName As String) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderName
System.String

The full folder name.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder. If the folder is empty, returns an empty collection.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty or folder was not found.

ListMessages(String, Int32, Int32)

Lists all messages in the selected folder in the specified range.

public ReadOnlyCollection<ExchangeMessageInfo> ListMessages(string folderName, int offset, int count)
Public Function ListMessages(folderName As String, offset As Integer, count As Integer) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderName
System.String

The folder name.

offset
System.Int32

Number of messages that should be skipped.

count
System.Int32

Number of messages that should be returned.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder. If folder is empty, returns an empty collection.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty or folder was not found.

ListMessagesById(String)

Lists all messages in the selected folder.

public ReadOnlyCollection<ExchangeMessageInfo> ListMessagesById(string folderId)
Public Function ListMessagesById(folderId As String) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderId
System.String

The folder id.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder. If the folder is empty, returns an empty collection.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder id is null or empty or folder was not found.

ListMessagesById(String, Int32, Int32)

Lists all messages in the selected folder in the specified range.

public ReadOnlyCollection<ExchangeMessageInfo> ListMessagesById(string folderId, int offset, int count)
Public Function ListMessagesById(folderId As String, offset As Integer, count As Integer) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderId
System.String

The folder id.

offset
System.Int32

Number of messages that should be skipped.

count
System.Int32

Number of messages that should be returned.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder. If folder is empty, returns an empty collection.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder id is null or empty or folder was not found.

MarkAllMessagesAsRead(String)

Marks all messages in a given folder as read.

public void MarkAllMessagesAsRead(string folderName)
Public Sub MarkAllMessagesAsRead(folderName As String)
Parameters
folderName
System.String

The name of the folder.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty or folder couldn't be found.

MarkMessageAsRead(String)

Marks message with a given id as read.

public void MarkMessageAsRead(string exchangeMessageId)
Public Sub MarkMessageAsRead(exchangeMessageId As String)
Parameters
exchangeMessageId
System.String

The Exchange message id.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Message id is null or empty.

MarkMessageAsUnread(String)

Marks message with a given id as unread.

public void MarkMessageAsUnread(string exchangeMessageId)
Public Sub MarkMessageAsUnread(exchangeMessageId As String)
Parameters
exchangeMessageId
System.String

The Exchange message id.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Message id is null or empty.

MoveMessage(String, String)

Moves the specified message to another folder.

public void MoveMessage(string messageId, string destinationFolder)
Public Sub MoveMessage(messageId As String, destinationFolder As String)
Parameters
messageId
System.String

The message id.

destinationFolder
System.String

The destination folder name.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Destination folder is null or empty.

RenameFolder(String, String)

Renames the folder.

public void RenameFolder(string oldName, string newName)
Public Sub RenameFolder(oldName As String, newName As String)
Parameters
oldName
System.String

Current folder full name.

newName
System.String

New folder full name.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Old folder name is null or empty or the folder wasn't found, or the new folder name is null or empty.

RenameFolderById(String, String)

Renames the folder.

public void RenameFolderById(string id, string newName)
Public Sub RenameFolderById(id As String, newName As String)
Parameters
id
System.String

The folder's id.

newName
System.String

New folder name.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Folder id is null or empty or the folder wasn't found, or the new folder name is null or empty.

SearchMessages(String, Int32, Int32, String)

Searches for messages that match the specified AQS query in the selected folder.

public ReadOnlyCollection<ExchangeMessageInfo> SearchMessages(string folderName, int offset, int count, string query)
Public Function SearchMessages(folderName As String, offset As Integer, count As Integer, query As String) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderName
System.String

The full folder name.

offset
System.Int32

Number of messages that should be skipped.

count
System.Int32

Number of messages that should be returned.

query
System.String

The query string in Advanced Query Syntax (AQS) format.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder that match the specified query.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty or folder was not found.

See Also

SearchMessages(String, String)

Searches for messages that match the specified AQS query in the selected folder.

public ReadOnlyCollection<ExchangeMessageInfo> SearchMessages(string folderName, string query)
Public Function SearchMessages(folderName As String, query As String) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderName
System.String

The full folder name.

query
System.String

The query string in Advanced Query Syntax (AQS) format.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder that match the specified query.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder name is null or empty or folder was not found.

See Also

SearchMessagesById(String, Int32, Int32, String)

Searches for messages that match the specified AQS query in the selected folder.

public ReadOnlyCollection<ExchangeMessageInfo> SearchMessagesById(string folderId, int offset, int count, string query)
Public Function SearchMessagesById(folderId As String, offset As Integer, count As Integer, query As String) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderId
System.String

The folder id.

offset
System.Int32

Number of messages that should be skipped.

count
System.Int32

Number of messages that should be returned.

query
System.String

The query string in Advanced Query Syntax (AQS) format.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder that match the specified query.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder id is null or empty or folder was not found.

See Also

SearchMessagesById(String, String)

Searches for messages that match the specified AQS query in the selected folder.

public ReadOnlyCollection<ExchangeMessageInfo> SearchMessagesById(string folderId, string query)
Public Function SearchMessagesById(folderId As String, query As String) As ReadOnlyCollection(Of ExchangeMessageInfo)
Parameters
folderId
System.String

The folder id.

query
System.String

The query string in Advanced Query Syntax (AQS) format.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<ExchangeMessageInfo>

A read-only collection of all messages in the selected folder that match the specified query.

Exceptions
System.InvalidOperationException

No folder is selected or Client could not be connected or Server error.

System.ArgumentException

Folder id is null or empty or folder was not found.

See Also

SendMessage(MailMessage)

Sends the message.

public void SendMessage(MailMessage message)
Public Sub SendMessage(message As MailMessage)
Parameters
message
MailMessage

The message.

Remarks

The message will also be saved to the SentItems folder.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

FreeLimitReachedException

Free license limitation exceeded.

SendMessage(MailMessage, Boolean)

Sends the message.

public void SendMessage(MailMessage message, bool saveOnSentItems)
Public Sub SendMessage(message As MailMessage, saveOnSentItems As Boolean)
Parameters
message
MailMessage

The message.

saveOnSentItems
System.Boolean

True if the message should be saved to the SentItems folder, otherwise false.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

FreeLimitReachedException

Free license limitation exceeded.

UploadMessage(MailMessage, String)

Uploads the specified message to the given folder.

public void UploadMessage(MailMessage message, string destinationFolder)
Public Sub UploadMessage(message As MailMessage, destinationFolder As String)
Parameters
message
MailMessage

The message.

destinationFolder
System.String

The destination folder name.

Exceptions
System.InvalidOperationException

Client could not be connected or Server error.

System.ArgumentException

Message is null, or destination folder is null or empty or the destination folder wasn't found.