🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
Auto-update documentation after merge [skip ci]
camel-docs-bot08bd137aaa08
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.jsonindex 2a9b532a9..6469b4785 100644--- a/docs/mintlify/docs.json+++ b/docs/mintlify/docs.json@@ -523,6 +523,7 @@"reference/camel.toolkits.human_toolkit","reference/camel.toolkits.image_analysis_toolkit","reference/camel.toolkits.image_generation_toolkit",+ "reference/camel.toolkits.imap_mail_toolkit","reference/camel.toolkits.jina_reranker_toolkit","reference/camel.toolkits.klavis_toolkit","reference/camel.toolkits.lark_toolkit",diff --git a/docs/mintlify/key_modules/tools.mdx b/docs/mintlify/key_modules/tools.mdxindex 868677607..2d4a75841 100644--- a/docs/mintlify/key_modules/tools.mdx+++ b/docs/mintlify/key_modules/tools.mdx@@ -111,6 +111,7 @@ CAMEL provides a variety of built-in toolkits that you can use right away. Here'| GoogleScholarToolkit | A toolkit for retrieving information about authors and their publications from Google Scholar. || HumanToolkit | A toolkit for facilitating human-in-the-loop interactions and feedback in AI systems. || ImageAnalysisToolkit | A toolkit for comprehensive image analysis and understanding using vision-capable language models. |+| IMAPMailToolkit | A toolkit for IMAP email operations to spring agents into email action || JinaRerankerToolkit | A toolkit for reranking documents (text or images) based on their relevance to a given query using the Jina Reranker model. || LinkedInToolkit | A toolkit for LinkedIn operations including creating posts, deleting posts, and retrieving user profile information. || MathToolkit | A toolkit for performing basic mathematical operations such as addition, subtraction, and multiplication. |diff --git a/docs/mintlify/reference/camel.toolkits.imap_mail_toolkit.mdx b/docs/mintlify/reference/camel.toolkits.imap_mail_toolkit.mdxnew file mode 100644index 000000000..b3d901783--- /dev/null+++ b/docs/mintlify/reference/camel.toolkits.imap_mail_toolkit.mdx@@ -0,0 +1,351 @@+<a id="camel.toolkits.imap_mail_toolkit"></a>++<a id="camel.toolkits.imap_mail_toolkit.IMAP_RETURN_STATUS"></a>++## IMAP_RETURN_STATUS++```python+class IMAP_RETURN_STATUS(Enum):+```++IMAP operation return status codes.++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit"></a>++## IMAPMailToolkit++```python+class IMAPMailToolkit(BaseToolkit):+```++A toolkit for IMAP email operations.++This toolkit provides comprehensive email functionality including:+- Fetching emails with filtering options+- Retrieving specific emails by ID+- Sending emails via SMTP+- Replying to emails+- Moving emails to folders+- Deleting emails++The toolkit implements connection pooling with automatic idle timeout+to prevent resource leaks when used by LLM agents.++**Parameters:**++- **imap_server** (str, optional): IMAP server hostname. If not provided, will be obtained from environment variables.+- **imap_port** (int, optional): IMAP server port. Defaults to 993. (default: 993)+- **smtp_server** (str, optional): SMTP server hostname. If not provided, will be obtained from environment variables.+- **smtp_port** (int, optional): SMTP server port. Defaults to 587. (default: 587)+- **username** (str, optional): Email username. If not provided, will be obtained from environment variables.+- **password** (str, optional): Email password. If not provided, will be obtained from environment variables.+- **timeout** (Optional[float]): The timeout for the toolkit operations.+- **connection_idle_timeout** (float): Maximum idle time (in seconds) before auto-closing connections. Defaults to 300 (5 minutes).++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.__init__"></a>++### __init__++```python+def __init__(+ self,+ imap_server: Optional[str] = None,+ imap_port: int = 993,+ smtp_server: Optional[str] = None,+ smtp_port: int = 587,+ username: Optional[str] = None,+ password: Optional[str] = None,+ timeout: Optional[float] = None,+ connection_idle_timeout: float = 300.0+):+```++Initialize the IMAP Mail Toolkit.++**Parameters:**++- **imap_server**: IMAP server hostname (default: :obj:`None`)+- **imap_port**: IMAP server port (default: :obj:`993`) (default: 993)+- **smtp_server**: SMTP server hostname (default: :obj:`None`)+- **smtp_port**: SMTP server port (default: :obj:`587`) (default: 587)+- **username**: Email username (default: :obj:`None`)+- **password**: Email password (default: :obj:`None`)+- **timeout**: Timeout for operations (default: :obj:`None`)+- **connection_idle_timeout**: Max idle time before auto-close (default: :obj:`300` seconds)++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit._get_imap_connection"></a>++### _get_imap_connection++```python+def _get_imap_connection(self):+```++**Returns:**++ imaplib.IMAP4_SSL: Connected IMAP client++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit._get_smtp_connection"></a>++### _get_smtp_connection++```python+def _get_smtp_connection(self):+```++**Returns:**++ smtplib.SMTP: Connected SMTP client++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit._ensure_imap_ok"></a>++### _ensure_imap_ok++```python+def _ensure_imap_ok(self, status: str, action: str):+```++Ensure IMAP status is OK, otherwise raise a ConnectionError.++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.fetch_emails"></a>++### fetch_emails++```python+def fetch_emails(+ self,+ folder: Literal['INBOX'] = 'INBOX',+ limit: int = 10,+ unread_only: bool = False,+ sender_filter: Optional[str] = None,+ subject_filter: Optional[str] = None+):+```++Fetch emails from a folder with optional filtering.++**Parameters:**++- **folder** (`Literal["INBOX"]`): Email folder to search in (default: :obj:`"INBOX"`)+- **limit** (int): Maximum number of emails to retrieve (default: :obj:`10`)+- **unread_only** (bool): If True, only fetch unread emails (default: :obj:`False`)+- **sender_filter** (str, optional): Filter emails by sender email address (default: :obj:`None`)+- **subject_filter** (str, optional): Filter emails by subject content (default: :obj:`None`)++**Returns:**++ List[Dict]: List of email dictionaries with metadata++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.get_email_by_id"></a>++### get_email_by_id++```python+def get_email_by_id(self, email_id: str, folder: Literal['INBOX'] = 'INBOX'):+```++Retrieve a specific email by ID with full metadata.++**Parameters:**++- **email_id** (str): ID of the email to retrieve+- **folder** (`Literal["INBOX"]`): Folder containing the email (default: :obj:`"INBOX"`)++**Returns:**++ Dict: Email dictionary with complete metadata++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.send_email"></a>++### send_email++```python+def send_email(+ self,+ to_recipients: List[str],+ subject: str,+ body: str,+ cc_recipients: Optional[List[str]] = None,+ bcc_recipients: Optional[List[str]] = None,+ html_body: Optional[str] = None+):+```++Send an email via SMTP.++**Parameters:**++- **to_recipients** (List[str]): List of recipient email addresses+- **subject** (str): Email subject line+- **body** (str): Plain text email body+- **cc_recipients** (List[str], optional): List of CC recipient email addresses+- **bcc_recipients** (List[str], optional): List of BCC recipient email addresses+- **html_body** (str, optional): HTML version of email body+- **extra_headers** (Dict[str, str], optional): Additional email headers++**Returns:**++ str: Success message++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.reply_to_email"></a>++### reply_to_email++```python+def reply_to_email(+ self,+ original_email_id: str,+ reply_body: str,+ folder: Literal['INBOX'] = 'INBOX',+ html_body: Optional[str] = None+):+```++Send a reply to an existing email.++**Parameters:**++- **original_email_id** (str): ID of the email to reply to+- **reply_body** (str): Reply message body+- **folder** (`Literal["INBOX"]`): Folder containing the original email (default: :obj:`"INBOX"`)+- **html_body** (str, optional): HTML version of reply body (default: :obj:`None`)++**Returns:**++ str: Success message++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.move_email_to_folder"></a>++### move_email_to_folder++```python+def move_email_to_folder(+ self,+ email_id: str,+ target_folder: str,+ source_folder: Literal['INBOX'] = 'INBOX'+):+```++Move an email to a different folder.++**Parameters:**++- **email_id** (str): ID of the email to move+- **target_folder** (str): Destination folder name+- **source_folder** (`Literal["INBOX"]`): Source folder name (default: :obj:`"INBOX"`)++**Returns:**++ str: Success message++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.delete_email"></a>++### delete_email++```python+def delete_email(+ self,+ email_id: str,+ folder: Literal['INBOX'] = 'INBOX',+ permanent: bool = False+):+```++Delete an email.++**Parameters:**++- **email_id** (str): ID of the email to delete+- **folder** (`Literal["INBOX"]`): Folder containing the email (default: :obj:`"INBOX"`)+- **permanent** (bool): If True, permanently delete the email (default: :obj:`False`)++**Returns:**++ str: Success message++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit._extract_email_body"></a>++### _extract_email_body++```python+def _extract_email_body(self, email_message: email.message.Message):+```++Extract plain text and HTML body from email message.++**Parameters:**++- **email_message**: Email message object++**Returns:**++ Dict[str, str]: Dictionary with 'plain' and 'html' body content++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.close"></a>++### close++```python+def close(self):+```++Close all open connections.++This method should be called when the toolkit is no longer needed+to properly clean up network connections.++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.__del__"></a>++### __del__++```python+def __del__(self):+```++Destructor to ensure connections are closed.++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.__enter__"></a>++### __enter__++```python+def __enter__(self):+```++**Returns:**++ IMAPMailToolkit: Self instance++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.__exit__"></a>++### __exit__++```python+def __exit__(+ self,+ exc_type,+ exc_val,+ exc_tb+):+```++Context manager exit, ensuring connections are closed.++**Parameters:**++- **exc_type**: Exception type if an exception occurred+- **exc_val**: Exception value if an exception occurred+- **exc_tb**: Exception traceback if an exception occurred++<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.get_tools"></a>++### get_tools++```python+def get_tools(self):+```++**Returns:**++ List[FunctionTool]: List of available tools