🔍 Code Extractor

class MailSearchFolder

Maturity: 51

A virtual folder class representing a mail search folder in Microsoft Exchange Online that contains email items matching specified search criteria.

File:
/tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/mail/folders/search.py
Lines:
4 - 11
Complexity:
moderate

Purpose

MailSearchFolder provides a specialized implementation of MailFolder for creating and managing virtual search folders in Exchange Online mailboxes. These folders dynamically contain email items that match defined search criteria. While search folders can be created in any mailbox folder, they must be created in the WellKnownFolderName.SearchFolders location to appear in Outlook, Outlook for the web, or Outlook Live. This class inherits all functionality from MailFolder and extends it for search-specific operations.

Source Code

class MailSearchFolder(MailFolder):
    """
    A mailSearchFolder is a virtual folder in the user's mailbox that contains all the email items
    matching specified search criteria. mailSearchFolder inherits from mailFolder.
    Search folders can be created in any folder in a user's Exchange Online mailbox. However, for a search folder
    to appear in Outlook, Outlook for the web, or Outlook Live, the folder must be created in the
    WellKnownFolderName.SearchFolders folder.
    """

Parameters

Name Type Default Kind
bases MailFolder -

Parameter Details

__init__: The constructor parameters are inherited from the parent MailFolder class. Typically includes context for API communication and optional parent folder reference.

Return Value

Instantiation returns a MailSearchFolder object that represents a virtual search folder. Methods inherited from MailFolder return various types including folder metadata, message collections, and operation results depending on the specific method called.

Class Interface

Methods

__init__(context, resource_path=None)

Purpose: Initializes a new MailSearchFolder instance (inherited from MailFolder)

Parameters:

  • context: The client context for API communication with Microsoft Graph
  • resource_path: Optional resource path for the folder in the API

Returns: A new MailSearchFolder instance

Attributes

Name Type Description Scope
display_name str The display name of the search folder (inherited from MailFolder) instance
source_folder_ids list[str] Collection of folder IDs that define the scope of the search instance
filter_query str OData filter query string that defines the search criteria for emails instance
messages MessageCollection Collection of messages that match the search criteria (inherited from MailFolder) instance
id str Unique identifier for the search folder (inherited from MailFolder) instance
parent_folder_id str The ID of the parent folder containing this search folder (inherited from MailFolder) instance

Dependencies

  • office365

Required Imports

from office365.outlook.mail.folders.search_folder import MailSearchFolder
from office365.outlook.mail.folders.folder import MailFolder

Usage Example

from office365.runtime.auth.client_credential import ClientCredential
from office365.graph_client import GraphClient
from office365.outlook.mail.folders.search_folder import MailSearchFolder

# Authenticate
credentials = ClientCredential(client_id, client_secret)
client = GraphClient(credentials)

# Get the search folders container
search_folders = client.me.mail_folders.get_by_name('SearchFolders').execute_query()

# Create a new search folder
new_search_folder = MailSearchFolder(client.me.mail_folders.context)
new_search_folder.display_name = 'Important Emails'
new_search_folder.source_folder_ids = ['inbox_folder_id']
new_search_folder.filter_query = 'importance eq high'
client.me.mail_folders.add(new_search_folder).execute_query()

# Access the created search folder
my_search_folder = client.me.mail_folders.get_by_id(new_search_folder.id).execute_query()
messages = my_search_folder.messages.get().execute_query()

Best Practices

  • Always create search folders in the WellKnownFolderName.SearchFolders location for visibility in Outlook clients
  • Ensure proper authentication and permissions (Mail.ReadWrite or Mail.ReadWrite.Shared) before creating or modifying search folders
  • Define clear and efficient filter queries to avoid performance issues with large mailboxes
  • Use the inherited methods from MailFolder for standard folder operations like listing messages, updating properties, or deleting
  • Remember that search folders are virtual - they don't physically contain messages but dynamically display results based on criteria
  • Handle API rate limits and implement retry logic for production applications
  • Always call execute_query() after operations to commit changes to the server
  • Clean up unused search folders to maintain mailbox organization and performance

Tags

email outlook exchange mail-folder search-folder virtual-folder microsoft-graph office365 mailbox email-search

Similar Components

AI-powered semantic similarity - components with related functionality:

  • class MailFolder 71.9% similar

    Represents a mail folder in a user's mailbox (e.g., Inbox, Drafts) that can contain messages, Outlook items, and child folders. Provides methods for folder operations like copying, emptying, and marking messages as read/unread.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/mail/folders/folder.py

  • class MailFolderCollection 63.3% similar

    A collection class for managing Microsoft Outlook mail folders with delta query support, inheriting from DeltaCollection to provide change tracking capabilities.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/mail/folders/collection.py

  • class SearchEntity 52.1% similar

    A wrapper class for the Microsoft Graph Search API endpoint that provides methods to query various Microsoft 365 resources including messages, events, drive items, and other entity types.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/search/entity.py

  • function search_for_folders 51.4% similar

    Searches for specific predefined folders in a SharePoint site using Microsoft Graph API and prints the search results with their locations.

    From: /tf/active/vicechatdev/SPFCsync/diagnostic_comprehensive.py

  • class CollaborationMailbox 51.3% similar

    A SharePoint entity class representing a collaboration mailbox, which is a specialized mailbox type used for team collaboration in SharePoint Online.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/portal/collaboration_mailbox.py
← Back to Browse