# python-sage-imap
[](https://codecov.io/gh/sageteamorg/python-sage-imap)
## Table of Contents
- [python-sage-imap](#python-sage-imap)
- [Table of Contents](#table-of-contents)
- [Introduction](#introduction)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Examples](#examples)
- [Example 1: Creating an IMAP Client](#example-1-creating-an-imap-client)
- [Explanation](#explanation)
- [Example 2: Working with Folder Service](#example-2-working-with-folder-service)
- [Example 3: Working with Mailbox Methods](#example-3-working-with-mailbox-methods)
- [IMAPMailboxService Example](#imapmailboxservice-example)
- [Example Usage with Nested Context Managers:](#example-usage-with-nested-context-managers)
- [License](#license)
## Introduction
`python-sage-imap` is a robust Python package designed for managing IMAP connections and performing various email operations. It provides easy-to-use interfaces for managing email folders, flags, searching emails, and sending emails using SMTP. This package is ideal for developers looking to integrate email functionalities into their applications seamlessly.
## Features
- Context manager for managing IMAP connections
- Handling IMAP flags (add/remove)
- Managing IMAP folders (create/rename/delete/list)
- Searching emails with various criteria
- Sending emails using SMTP with support for attachments and templates
- Parsing and handling email messages
## Installation
To install `python-sage-imap`, use pip:
```bash
pip install python-sage-imap
```
## Configuration
Before using the package, you need to set up logging for better debugging and monitoring:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
## Examples
### Example 1: Creating an IMAP Client
This example demonstrates how to create an IMAP client using the `IMAPClient` class.
The `IMAPClient` class can also be used without a context manager; simply call `connect()` to establish the connection and `disconnect()` to close it
```python
from sage_imap.services import IMAPClient
with IMAPClient('imap.example.com', 'username', 'password') as client:
# Use the client for IMAP operations
capabilities = client.capability()
print(f"Server capabilities: {capabilities}")
status, messages = client.select("INBOX")
print(f"Selected INBOX with status: {status}")
```
#### Explanation
This example illustrates a low-level approach to working with IMAP. If you want to use `imaplib` directly but need the added convenience of managing the connection lifecycle, the `IMAPClient` class is a perfect choice. It allows you to create a connection with the IMAP server and then use all the capabilities of `imaplib` to customize your workflow.
1. **IMAPClient Context Manager**:
- The `IMAPClient` class is used within a context manager (`with` statement). This ensures that the connection to the IMAP server is properly opened and closed.
- When the `with` block is entered, the connection to the IMAP server is established, and the user is authenticated.
- When the `with` block is exited, the connection is automatically closed, ensuring that resources are cleaned up properly.
2. **Why Use IMAPClient**:
- The `IMAPClient` exists to simplify the management of IMAP connections. By using it as a context manager, you don't have to worry about manually opening and closing the connection. This reduces the risk of resource leaks and makes your code cleaner and more maintainable.
- Within the context manager, you have access to the `imaplib` capabilities directly through the `client` object. This allows you to perform various IMAP operations seamlessly.
3. **Capabilities and Select Methods**:
- The `.capability()` method is called to retrieve the server's capabilities, providing information about what commands and features the server supports.
- The `.select("INBOX")` method is used to select the "INBOX" mailbox for further operations. It returns the status of the selection and the number of messages in the mailbox.
By using the `IMAPClient` class in this way, you can take advantage of the full power of `imaplib` while benefiting from the convenience and safety of automatic connection management.
### Example 2: Working with Folder Service
This example demonstrates how to work with folders using the `IMAPFolderService`.
```python
from sage_imap.services.client import IMAPClient
from sage_imap.services.folder import IMAPFolderService
with IMAPClient('imap.example.com', 'username', 'password') as client:
folder_service = IMAPFolderService(client)
# Create a new folder
folder_service.create_folder('NewFolder')
# Rename the folder
folder_service.rename_folder('NewFolder', 'RenamedFolder')
# List all folders
folders = folder_service.list_folders()
print(f"Folders: {folders}")
# Delete the folder
folder_service.delete_folder('RenamedFolder')
```
### Example 3: Working with Mailbox Methods
Below are usage examples of the `IMAPClient` and `IMAPMailboxService` classes, demonstrating their context manager capabilities and various methods:
### IMAPMailboxService Example
The `IMAPMailboxService` class provides methods for managing mailbox operations such as selecting, closing, checking, deleting, moving, and getting status of mailboxes.
**Purpose:** This class allows for performing various mailbox-related operations within the context of an IMAP connection, ensuring proper error handling and cleanup.
#### Example Usage with Nested Context Managers:
```python
from sage_imap.services.client import IMAPClient
from sage_imap.services.mailbox import IMAPMailboxService
from sage_imap.helpers.mailbox import DefaultMailboxes
from sage_imap.helpers.message import MessageSet
from helpers.exceptions import IMAPClientError, IMAPMailboxCheckError, IMAPMailboxClosureError
username = 'username'
password = 'password'
try:
with IMAPClient('imap.example.com', username, password) as client:
with IMAPMailboxService(client) as mailbox:
# Select a mailbox
mailbox.select(DefaultMailboxes.INBOX)
# Delete messages temporarily (move to trash)
msg_set = MessageSet('1,2,3')
mailbox.trash(msg_set)
# Restore messages from trash to original folder
mailbox.restore(msg_set, DefaultMailboxes.INBOX)
# Permanently delete messages
mailbox.delete(msg_set)
except IMAPClientError as e:
print(f"An error occurred with the IMAP client: {e}")
```
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/sageteamorg/python-sage-imap",
"name": "python-sage-imap",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "python, imap, email, mailbox, python-packages",
"author": "Sepehr Akbarzadeh",
"author_email": "sepehr@sageteam.org",
"download_url": "https://files.pythonhosted.org/packages/b3/5e/c01afaa9c16ead779916b037696ecc9e8c1eac492f80598c43d07d15b073/python_sage_imap-0.4.8.tar.gz",
"platform": null,
"description": "# python-sage-imap\n\n\n\n\n[](https://codecov.io/gh/sageteamorg/python-sage-imap)\n\n![PyPI release](https://img.shields.io/pypi/v/python-sage-imap \"python-sage-imap\")\n![Supported Python versions](https://img.shields.io/pypi/pyversions/python-sage-imap \"python-sage-imap\")\n![Documentation](https://img.shields.io/readthedocs/python-sage-imap \"python-sage-imap\")\n\n\n\n\n## Table of Contents\n- [python-sage-imap](#python-sage-imap)\n - [Table of Contents](#table-of-contents)\n - [Introduction](#introduction)\n - [Features](#features)\n - [Installation](#installation)\n - [Configuration](#configuration)\n - [Examples](#examples)\n - [Example 1: Creating an IMAP Client](#example-1-creating-an-imap-client)\n - [Explanation](#explanation)\n - [Example 2: Working with Folder Service](#example-2-working-with-folder-service)\n - [Example 3: Working with Mailbox Methods](#example-3-working-with-mailbox-methods)\n - [IMAPMailboxService Example](#imapmailboxservice-example)\n - [Example Usage with Nested Context Managers:](#example-usage-with-nested-context-managers)\n - [License](#license)\n\n## Introduction\n`python-sage-imap` is a robust Python package designed for managing IMAP connections and performing various email operations. It provides easy-to-use interfaces for managing email folders, flags, searching emails, and sending emails using SMTP. This package is ideal for developers looking to integrate email functionalities into their applications seamlessly.\n\n## Features\n- Context manager for managing IMAP connections\n- Handling IMAP flags (add/remove)\n- Managing IMAP folders (create/rename/delete/list)\n- Searching emails with various criteria\n- Sending emails using SMTP with support for attachments and templates\n- Parsing and handling email messages\n\n## Installation\nTo install `python-sage-imap`, use pip:\n```bash\npip install python-sage-imap\n```\n\n## Configuration\nBefore using the package, you need to set up logging for better debugging and monitoring:\n```python\nimport logging\n\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## Examples\n\n### Example 1: Creating an IMAP Client\n\nThis example demonstrates how to create an IMAP client using the `IMAPClient` class.\n\nThe `IMAPClient` class can also be used without a context manager; simply call `connect()` to establish the connection and `disconnect()` to close it\n\n```python\nfrom sage_imap.services import IMAPClient\n\nwith IMAPClient('imap.example.com', 'username', 'password') as client:\n # Use the client for IMAP operations\n capabilities = client.capability()\n print(f\"Server capabilities: {capabilities}\")\n\n status, messages = client.select(\"INBOX\")\n print(f\"Selected INBOX with status: {status}\")\n```\n\n#### Explanation\n\nThis example illustrates a low-level approach to working with IMAP. If you want to use `imaplib` directly but need the added convenience of managing the connection lifecycle, the `IMAPClient` class is a perfect choice. It allows you to create a connection with the IMAP server and then use all the capabilities of `imaplib` to customize your workflow.\n\n1. **IMAPClient Context Manager**:\n - The `IMAPClient` class is used within a context manager (`with` statement). This ensures that the connection to the IMAP server is properly opened and closed.\n - When the `with` block is entered, the connection to the IMAP server is established, and the user is authenticated.\n - When the `with` block is exited, the connection is automatically closed, ensuring that resources are cleaned up properly.\n\n2. **Why Use IMAPClient**:\n - The `IMAPClient` exists to simplify the management of IMAP connections. By using it as a context manager, you don't have to worry about manually opening and closing the connection. This reduces the risk of resource leaks and makes your code cleaner and more maintainable.\n - Within the context manager, you have access to the `imaplib` capabilities directly through the `client` object. This allows you to perform various IMAP operations seamlessly.\n\n3. **Capabilities and Select Methods**:\n - The `.capability()` method is called to retrieve the server's capabilities, providing information about what commands and features the server supports.\n - The `.select(\"INBOX\")` method is used to select the \"INBOX\" mailbox for further operations. It returns the status of the selection and the number of messages in the mailbox.\n\nBy using the `IMAPClient` class in this way, you can take advantage of the full power of `imaplib` while benefiting from the convenience and safety of automatic connection management.\n\n\n### Example 2: Working with Folder Service\nThis example demonstrates how to work with folders using the `IMAPFolderService`.\n\n```python\nfrom sage_imap.services.client import IMAPClient\nfrom sage_imap.services.folder import IMAPFolderService\n\nwith IMAPClient('imap.example.com', 'username', 'password') as client:\n folder_service = IMAPFolderService(client)\n\n # Create a new folder\n folder_service.create_folder('NewFolder')\n\n # Rename the folder\n folder_service.rename_folder('NewFolder', 'RenamedFolder')\n\n # List all folders\n folders = folder_service.list_folders()\n print(f\"Folders: {folders}\")\n\n # Delete the folder\n folder_service.delete_folder('RenamedFolder')\n```\n\n### Example 3: Working with Mailbox Methods\n\nBelow are usage examples of the `IMAPClient` and `IMAPMailboxService` classes, demonstrating their context manager capabilities and various methods:\n\n### IMAPMailboxService Example\n\nThe `IMAPMailboxService` class provides methods for managing mailbox operations such as selecting, closing, checking, deleting, moving, and getting status of mailboxes.\n\n**Purpose:** This class allows for performing various mailbox-related operations within the context of an IMAP connection, ensuring proper error handling and cleanup.\n\n#### Example Usage with Nested Context Managers:\n\n```python\nfrom sage_imap.services.client import IMAPClient\nfrom sage_imap.services.mailbox import IMAPMailboxService\nfrom sage_imap.helpers.mailbox import DefaultMailboxes\nfrom sage_imap.helpers.message import MessageSet\n\nfrom helpers.exceptions import IMAPClientError, IMAPMailboxCheckError, IMAPMailboxClosureError\n\nusername = 'username'\npassword = 'password'\n\ntry:\n with IMAPClient('imap.example.com', username, password) as client:\n with IMAPMailboxService(client) as mailbox:\n # Select a mailbox\n mailbox.select(DefaultMailboxes.INBOX)\n\n # Delete messages temporarily (move to trash)\n msg_set = MessageSet('1,2,3')\n mailbox.trash(msg_set)\n\n # Restore messages from trash to original folder\n mailbox.restore(msg_set, DefaultMailboxes.INBOX)\n\n # Permanently delete messages\n mailbox.delete(msg_set)\n\nexcept IMAPClientError as e:\n print(f\"An error occurred with the IMAP client: {e}\")\n```\n\n## License\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for managing IMAP connections and email operations.",
"version": "0.4.8",
"project_urls": {
"Documentation": "https://python-sage-imap.readthedocs.io/en/latest/",
"Homepage": "https://github.com/sageteamorg/python-sage-imap",
"Issues": "https://github.com/sageteamorg/python-sage-imap/issues",
"Repository": "https://github.com/sageteamorg/python-sage-imap",
"Source Code": "https://github.com/sageteamorg/python-sage-imap"
},
"split_keywords": [
"python",
" imap",
" email",
" mailbox",
" python-packages"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9df2ffec11a6d08b195bcded488c1bdf07a6a1544f84463e68014db1d45b0359",
"md5": "77c5f9a2f2f96c91addee3fcd198814c",
"sha256": "4e7c74900b6c71573773951a2f7a0169ac178ff58261b0b1aa8292efe8bdb456"
},
"downloads": -1,
"filename": "python_sage_imap-0.4.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77c5f9a2f2f96c91addee3fcd198814c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 25940,
"upload_time": "2024-10-26T08:10:03",
"upload_time_iso_8601": "2024-10-26T08:10:03.270361Z",
"url": "https://files.pythonhosted.org/packages/9d/f2/ffec11a6d08b195bcded488c1bdf07a6a1544f84463e68014db1d45b0359/python_sage_imap-0.4.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b35ec01afaa9c16ead779916b037696ecc9e8c1eac492f80598c43d07d15b073",
"md5": "4febebc3646f49e2d45519d7bb246d1c",
"sha256": "2da694c00ada762d729de45f2ec9ec8d08e5218489dcca35e3a182d21f2038c1"
},
"downloads": -1,
"filename": "python_sage_imap-0.4.8.tar.gz",
"has_sig": false,
"md5_digest": "4febebc3646f49e2d45519d7bb246d1c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 25060,
"upload_time": "2024-10-26T08:10:05",
"upload_time_iso_8601": "2024-10-26T08:10:05.322441Z",
"url": "https://files.pythonhosted.org/packages/b3/5e/c01afaa9c16ead779916b037696ecc9e8c1eac492f80598c43d07d15b073/python_sage_imap-0.4.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 08:10:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sageteamorg",
"github_project": "python-sage-imap",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "python-sage-imap"
}
JSON
