> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camel-ai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Camel.toolkits.imap mail toolkit

<a id="camel.toolkits.imap_mail_toolkit" />

<a id="camel.toolkits.imap_mail_toolkit.IMAP_RETURN_STATUS" />

## IMAP\_RETURN\_STATUS

```python theme={"system"}
class IMAP_RETURN_STATUS(Enum):
```

IMAP operation return status codes.

<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit" />

## IMAPMailToolkit

```python theme={"system"}
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__" />

### **init**

```python theme={"system"}
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" />

### \_get\_imap\_connection

```python theme={"system"}
def _get_imap_connection(self):
```

**Returns:**

imaplib.IMAP4\_SSL: Connected IMAP client

<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit._get_smtp_connection" />

### \_get\_smtp\_connection

```python theme={"system"}
def _get_smtp_connection(self):
```

**Returns:**

smtplib.SMTP: Connected SMTP client

<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit._ensure_imap_ok" />

### \_ensure\_imap\_ok

```python theme={"system"}
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" />

### fetch\_emails

```python theme={"system"}
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" />

### get\_email\_by\_id

```python theme={"system"}
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" />

### send\_email

```python theme={"system"}
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" />

### reply\_to\_email

```python theme={"system"}
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" />

### move\_email\_to\_folder

```python theme={"system"}
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" />

### delete\_email

```python theme={"system"}
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" />

### \_extract\_email\_body

```python theme={"system"}
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" />

### close

```python theme={"system"}
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__" />

### **del**

```python theme={"system"}
def __del__(self):
```

Destructor to ensure connections are closed.

<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.__enter__" />

### **enter**

```python theme={"system"}
def __enter__(self):
```

**Returns:**

IMAPMailToolkit: Self instance

<a id="camel.toolkits.imap_mail_toolkit.IMAPMailToolkit.__exit__" />

### **exit**

```python theme={"system"}
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" />

### get\_tools

```python theme={"system"}
def get_tools(self):
```

**Returns:**

List\[FunctionTool]: List of available tools