Skip to content

Add support for resolving special-use folders - #184

Merged
stevebauman merged 6 commits into
v2.0from
feature/v2-special-use-folders
Sep 2, 2026
Merged

Add support for resolving special-use folders#184
stevebauman merged 6 commits into
v2.0from
feature/v2-special-use-folders

Conversation

@stevebauman

@stevebauman stevebauman commented Sep 2, 2026

Copy link
Copy Markdown
Member

IMAP servers can identify standard folders such as Sent, Drafts, Trash, and Archive using RFC 6154 special-use attributes. ImapEngine currently requires consumers to inspect raw mailbox attributes and resolve these folders themselves.

This adds a typed folder data builder that allows consumers to explicitly request supported LIST return data:

$folders = $mailbox->folders()
    ->with(FolderData::SpecialUse)
    ->get();

$sent = $folders->findBySpecialUse(ImapSpecialUse::Sent);

Folder data items share a FolderDataItem contract so parameterized return options can use the same with() API as support for additional extended LIST data is added. Requested capabilities are validated before the command is sent.

Folder mailbox flags have also been renamed to attributes throughout the public API to match IMAP terminology and distinguish them from message flags. FolderCollection resolves the typed ImapSpecialUse enum directly from these attributes, keeping special-use methods off the folder interface. Attributes included voluntarily in ordinary LIST responses are also recognized. Resolution relies exclusively on RFC attributes and returns null instead of guessing from language-dependent folder names. The fake folder repository supports the same builder API for application tests.

@stevebauman
stevebauman merged commit c22065c into v2.0 Sep 2, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant