Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

Auto-update documentation after merge [skip ci]

camel-docs-bot08bd137aaa08
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json
index 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.mdx
index 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.mdx
new file mode 100644
index 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