Method CreateFolderAsync

Namespace: MailFathom.Application.Folders

Assembly: MailFathom.Application.dll

CreateFolderAsync(MailAccountId, MailFolderAlias, RemoteFolderPath, MailTransportSecurityPolicy, CancellationToken)

Creates the folder a configured path names, together with the ancestors that path names above it.

Task<RemoteFolderPath> CreateFolderAsync(MailAccountId accountId, MailFolderAlias folderAlias, RemoteFolderPath configuredPath, MailTransportSecurityPolicy transportSecurityPolicy, CancellationToken cancellationToken)

Parameters

accountId MailAccountId: The account whose mailbox gains the folder.
folderAlias MailFolderAlias: The folder alias the path was configured under, which is the name every failure reports.
configuredPath RemoteFolderPath: The path the operator wrote, which is used exactly as written and never rewritten.
transportSecurityPolicy MailTransportSecurityPolicy: The connection and authentication policy the implementation must obey.
cancellationToken CancellationToken: Cancels waiting for the account's write connection, connecting, authenticating, and creating.

Returns

Task<RemoteFolderPath>: The created folder as the server advertises it, with the hierarchy delimiter the server reported.

Remarks

A folder already at that path is the successful answer rather than a failure, because another mail client — or another MailFathom process — may have created it between the listing that found nothing and this attempt. The path comes back as the server advertises it either way, so a caller binds a created folder exactly as it binds a discovered one.

The folder is subscribed to as part of creating it, so it appears in a mail client that lists subscriptions and the operator can find the mail a rule files there. A server that refuses the subscription does not fail the creation: the folder exists, which is what was asked for.

Exceptions

ArgumentNullException: Thrown when transportSecurityPolicy is null.
RemoteFolderCreationRefusedException: Thrown when the mail server answered and refused to hold a folder at that path.
MailboxUnavailableException: Thrown when the mail server did not serve the creation within its configured resilience budget.