New command: `m365 outlook mail searchfolder add`

MartinM85 commented 2 weeks ago

Usage

m365 outlook mail searchfolder add [options]

Description

Creates a new mail search folder in the user's mailbox

Options

Option	Description
`-i, --userId [userId]`	The id of the user in whose mailbox the search folder should be created. Specify either `userId` or `userName`, but not both.
`-n, --userName [userName]`	The UPN of the user in whose mailbox the search folder should be created. Specify either `userId` or `userName`, but not both.
`--folderName <folderName>`	The name of the mail search folder.
`--sourceFolderIds <sourceFolderIds>`	Comma-separated list of mail folders that should be searched.
`--includeNestedFolders`	The nested mail folders will be searched if specified.
`--messageFilter <messageFilter>`	The OData query to filter the messages.

Examples

Create a mail search folder in the user's mailbox specified by id for messages from the inbox that contain specific subject

m365 outlook mail searchfolder add --userId 1caf7dcd-7e83-4c3a-94f7-932a1299c844 --folderName 'CLI m365' --sourceFolderIds 'AQMkADYAAAIBDAAAAA==' --messageFilter "contains(subject, 'CLI for Microsoft 365')"

Create a mail search folder in the user's mailbox specified by UPN for incoming and outgoing messages from a specific year that contain specific text in a message body, search for messages inside all subfolders

m365 outlook mail searchfolder add --userName john.doe@contoso.com --folderName 'Power Platform Community' --sourceFolderIds 'AQMkADYAAAIBDAAAAA==,AQMkADYAAAIBDBBBBB==' --includeNestedFolders --messageFilter "contains(body/content,'Power Platform') AND receivedDateTime ge 2024-01-01 AND receivedDateTime le 2024-12-31"

Additional Info

The command requires Mail.ReadWrite permission.

More info: https://learn.microsoft.com/graph/api/mailsearchfolder-post?view=graph-rest-1.0&tabs=http

I will work on it

Jwaegebaert commented 2 weeks ago

Thanks for writing out the specs, @MartinM85. I've got a few remarks before we move forward:

For the includeNestedFolders option, wouldn't it make more sense to have the default set to false? If they want to include nested folders, they could just specify the --includeNestedFolders flag without needing to define a boolean.
We might want to tweak the command name a bit to make it more future-proof. For example, we could have commands that add general mail folders. Something like m365 outlook mail searchfolder add might work better. @pnp/cli-for-microsoft-365-maintainers, what do you think?

MartinM85 commented 1 week ago

@Jwaegebaert m365 outlook mail searchfolder add makes more sense. Spec updated

Jwaegebaert commented 1 week ago

Awesome, that works better. One more detail before we open up, regarding includeNestedFolders. Instead of saying in the description that the default is false, I was rather considering converting this option to a flag. That when specified, you nest those folders. A bit similar to the default and personal flags you have in spo list view add. Be sure to also update the examples as well when you change this.

MartinM85 commented 1 week ago

@Jwaegebaert Spec updated

Jwaegebaert commented 1 week ago

Awesome work @MartinM85! I've assigned it to you.

pnp / cli-microsoft365