https://github.com/sageteamorg/python-sage-imap
Managing IMAP connections and performing various email operations.
https://github.com/sageteamorg/python-sage-imap
email imap mailbox python
Last synced: about 2 months ago
JSON representation
Managing IMAP connections and performing various email operations.
- Host: GitHub
- URL: https://github.com/sageteamorg/python-sage-imap
- Owner: sageteamorg
- License: mit
- Created: 2024-07-04T07:20:26.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-10-26T08:09:39.000Z (8 months ago)
- Last Synced: 2024-12-30T11:52:18.917Z (5 months ago)
- Topics: email, imap, mailbox, python
- Language: Python
- Homepage: https://python-sage-imap.readthedocs.io/
- Size: 313 KB
- Stars: 5
- Watchers: 2
- Forks: 5
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 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.