Email Clients

The email client modules provide functionality for sending and receiving emails through different protocols and services.

BaseEmailClient

class pymailai.base_client.BaseEmailClient[source]

Bases: ABC

Abstract base class for email clients.

The BaseEmailClient class defines the interface for all email clients:

Abstract base class for email operations
Defines standard methods for email handling
Provides async context manager support

Example of implementing a custom client:

from pymailai.base_client import BaseEmailClient
from pymailai.message import EmailData

class MyCustomClient(BaseEmailClient):
    async def connect(self) -> None:
        # Connect to email service
        pass

    async def disconnect(self) -> None:
        # Disconnect from service
        pass

    async def fetch_new_messages(self) -> AsyncGenerator[EmailData, None]:
        # Fetch new messages
        pass

    async def send_message(self, message: EmailData) -> None:
        # Send a message
        pass

    async def mark_as_read(self, message_id: str) -> None:
        # Mark message as read
        pass

abstract async connect()[source]

Connect to the email service.

Return type:: None

abstract async disconnect()[source]

Disconnect from the email service.

Return type:: None

abstract async fetch_new_messages()[source]

Fetch new messages from the email service.

Yields:: EmailData objects for new messages.
Return type:: AsyncGenerator[EmailData, None]

abstract async send_message(message)[source]

Send an email message.

Parameters:: message (EmailData)
Return type:: None

abstract async mark_as_read(message_id)[source]

Mark a message as read.

Parameters:: message_id (str)
Return type:: None

abstract async query_messages(query_params)[source]

Query messages based on specified parameters.

Parameters:: query_params (dict) – Dictionary containing query parameters: - after_date: Optional[str] - Messages after this date (YYYY-MM-DD) - before_date: Optional[str] - Messages before this date (YYYY-MM-DD) - subject: Optional[str] - Subject line contains this text - from_address: Optional[str] - Sender email address - to_address: Optional[str] - Recipient email address - label: Optional[str] - Message label/folder - unread_only: Optional[bool] - Only unread messages if True - include_body: Optional[bool] - Include message body in results
Yields:: EmailData objects for matching messages
Return type:: AsyncGenerator[EmailData, None]

IMAP/SMTP Client

class pymailai.client.EmailClient(config)[source]

Bases: BaseEmailClient

Asynchronous email client for IMAP and SMTP operations.

The EmailClient class provides IMAP/SMTP email operations with:

Improved SMTP connection handling with automatic reconnection
Comprehensive logging for debugging and monitoring
Support for Gmail OAuth2 authentication
Enhanced error handling for common email operations

Example usage:

from pymailai.client import EmailClient
from pymailai.config import EmailConfig

# Using standard IMAP/SMTP
config = EmailConfig(
    imap_server="imap.gmail.com",
    smtp_server="smtp.gmail.com",
    email="your-email@gmail.com",
    password="your-password"
)
client = EmailClient(config)

# Using OAuth2 credentials
client = EmailClient.from_gmail_oauth2(
    email="your-email@gmail.com",
    credentials_path="~/.config/pymailai/gmail_creds.json"
)

Parameters:: config (EmailConfig)

__init__(config)[source]

Initialize email client with configuration.

Parameters:: config (EmailConfig)

async connect()[source]

Establish connections to IMAP and SMTP servers.

Return type:: None

async disconnect()[source]

Close connections to email servers.

Return type:: None

async fetch_new_messages()[source]

Fetch new unread messages from the IMAP server.

Return type:: AsyncGenerator[EmailData, None]

async send_message(message, max_retries=3)[source]

Send an email message via SMTP with automatic reconnection and retries.

Parameters:

message (EmailData) – The email message to send
max_retries (int) – Maximum number of retry attempts (default: 3)

Return type:

None

async mark_as_read(message_id)[source]

Mark a message as read using its Message-ID.

Parameters:: message_id (str)
Return type:: None

async query_messages(query_params)[source]

Query messages using IMAP search criteria.

Parameters:: query_params (dict) – Dictionary containing query parameters: - after_date: Optional[str] - Messages after this date (YYYY-MM-DD) - before_date: Optional[str] - Messages before this date (YYYY-MM-DD) - subject: Optional[str] - Subject line contains this text - from_address: Optional[str] - Sender email address - to_address: Optional[str] - Recipient email address - label: Optional[str] - Message folder (defaults to INBOX) - unread_only: Optional[bool] - Only unread messages if True - include_body: Optional[bool] - Include message body in results
Return type:: AsyncGenerator[EmailData, None]

Gmail API Client

class pymailai.gmail_client.GmailClient(service)[source]

Bases: BaseEmailClient

Asynchronous Gmail client using the Gmail API.

The GmailClient class provides direct Gmail API access with:

Service account authentication support
Direct Gmail API operations
Enhanced message handling
Proper email threading

Example usage with service account:

from pymailai.gmail import ServiceAccountCredentials
from pymailai.gmail_client import GmailClient

# Set up service account
creds = ServiceAccountCredentials(
    credentials_path="credentials.json",
    delegated_email="user@yourdomain.com",
    scopes=["https://www.googleapis.com/auth/gmail.modify"]
)

# Create Gmail client
client = GmailClient(creds.get_gmail_service())

# Use with EmailAgent
agent = EmailAgent(client, message_handler=handler)

__init__(service)[source]: Initialize Gmail client with service.

async connect()[source]

No connection needed for Gmail API.

Return type:: None

async disconnect()[source]

No disconnection needed for Gmail API.

Return type:: None

async fetch_new_messages()[source]

Fetch new unread messages using Gmail API.

Return type:: AsyncGenerator[EmailData, None]

async send_message(message)[source]

Send an email message via Gmail API.

Parameters:: message (EmailData)
Return type:: None

async mark_as_read(message_id)[source]

Mark a message as read using Gmail API.

Parameters:: message_id (str) – Gmail message ID to mark as read
Return type:: None

async query_messages(query_params)[source]

Query messages using Gmail API with specified parameters.

Parameters:: query_params (dict)
Return type:: AsyncGenerator[EmailData, None]

The client automatically handles connection management and authentication. All operations are logged for debugging purposes.