Email Clients

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

BaseEmailClient

class pymailai.base_client.BaseEmailClient

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()

Connect to the email service.

Return type:

None

abstract async disconnect()

Disconnect from the email service.

Return type:

None

abstract async fetch_new_messages()

Fetch new messages from the email service.

Yields:

EmailData objects for new messages.

Return type:

AsyncGenerator[EmailData, None]

abstract async send_message(message)

Send an email message.

Parameters:

message (EmailData)

Return type:

None

abstract async mark_as_read(message_id)

Mark a message as read.

Parameters:

message_id (str)

Return type:

None

IMAP/SMTP Client

class pymailai.client.EmailClient(config)

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)

Initialize email client with configuration.

Parameters:

config (EmailConfig)

async connect()

Establish connections to IMAP and SMTP servers.

Return type:

None

async disconnect()

Close connections to email servers.

Return type:

None

async fetch_new_messages()

Fetch new unread messages from the IMAP server.

Return type:

AsyncGenerator[EmailData, None]

async send_message(message)

Send an email message via SMTP.

Parameters:

message (EmailData)

Return type:

None

async mark_as_read(message_id)

Mark a message as read using its Message-ID.

Parameters:

message_id (str)

Return type:

None

Gmail API Client

class pymailai.gmail_client.GmailClient(service)

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)

Initialize Gmail client with service.

async connect()

No connection needed for Gmail API.

Return type:

None

async disconnect()

No disconnection needed for Gmail API.

Return type:

None

async fetch_new_messages()

Fetch new unread messages using Gmail API.

Return type:

AsyncGenerator[EmailData, None]

async send_message(message)

Send an email message via Gmail API.

Parameters:

message (EmailData)

Return type:

None

async mark_as_read(message_id)

Mark a message as read using Gmail API.

Parameters:

message_id (str) – Gmail message ID to mark as read

Return type:

None

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