Quick Start Guide

This guide will help you get started with pymailai quickly.

Installation

Install pymailai with pip:

pip install pymailai

Basic Usage

Here’s a simple example of creating an email agent that processes incoming emails:

import asyncio
import os
from typing import Optional

from pymailai import EmailAgent, EmailConfig
from pymailai.message import EmailData

async def message_handler(message: EmailData) -> Optional[EmailData]:
    """Process incoming emails and generate responses."""
    return EmailData(
        message_id="",  # Will be generated by email server
        subject=f"Re: {message.subject}",
        from_address=message.to_addresses[0],
        to_addresses=[message.from_address],
        cc_addresses=[],
        body_text=f"Received your message: {message.body_text}",
        body_html=None,
        timestamp=message.timestamp,
        in_reply_to=message.message_id,
        references=[message.message_id]
    )

async def main():
    # Configure email settings
    config = EmailConfig(
        imap_server=os.getenv("EMAIL_IMAP_SERVER", "imap.gmail.com"),
        smtp_server=os.getenv("EMAIL_SMTP_SERVER", "smtp.gmail.com"),
        email=os.getenv("EMAIL_ADDRESS"),
        password=os.getenv("EMAIL_PASSWORD")
    )

    # Create and run email agent
    async with EmailAgent(config, message_handler=message_handler) as agent:
        print(f"Email agent started. Monitoring {config.email}")
        print("Press Ctrl+C to stop...")

        try:
            while True:
                await asyncio.sleep(1)
        except KeyboardInterrupt:
            print("\nStopping email agent...")

if __name__ == "__main__":
    asyncio.run(main())

Gmail Authentication

pymailai supports two methods for Gmail authentication:

  1. OAuth2 (for personal Gmail accounts)

  2. Service Account (for Google Workspace accounts)

OAuth2 Setup (Personal Gmail)

For personal Gmail accounts, OAuth2 authentication is recommended:

  1. Install with Gmail support:

    pip install pymailai[gmail]

  2. Set up Google Cloud Project:

    1. Go to the Google Cloud Console

    2. Create a new project or select an existing one

    3. Enable the Gmail API

    4. Create OAuth2 credentials (Desktop application type)

    5. Download the credentials

  3. Get refresh token using the helper script:

    # Set required environment variables
export GMAIL_CLIENT_ID="your-client-id"
export GMAIL_CLIENT_SECRET="your-client-secret"

# Run the helper script
python examples/get_gmail_token.py

  4. Use Gmail credentials in your code:

from pathlib import Path
from pymailai import EmailAgent
from pymailai.gmail import GmailCredentials

async def main():
    # Load Gmail credentials
    creds_path = Path.home() / ".config" / "pymailai" / "gmail_creds.json"
    creds = GmailCredentials(creds_path)

    # Convert to EmailConfig
    config = creds.to_email_config("your-email@gmail.com")

    # Create and run agent
    async with EmailAgent(config, message_handler=message_handler) as agent:
        # ... rest of the code ...

Service Account Setup (Google Workspace)

For Google Workspace accounts, service account authentication provides better security and control:

  1. Set up Google Cloud Project:

    1. Go to the Google Cloud Console

    2. Create a new project or select an existing one

    3. Enable the Gmail API

    4. Create a service account

    5. Download the service account JSON key file

  2. Configure Google Workspace:

    1. Go to Admin Console -> Security -> API Controls

    2. Under “Domain-wide Delegation”, add your service account

    3. Add the required scope: https://www.googleapis.com/auth/gmail.modify

  3. Use service account in your code:

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

async def main():
    # Set up service account authentication
    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())

    # Create and run agent
    async with EmailAgent(client, message_handler=message_handler) as agent:
        # ... rest of the code ...

Custom Email Clients

pymailai provides a BaseEmailClient interface for implementing custom email clients:

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

AI Integration

pymailai supports integration with various AI providers:

OpenAI Example

pip install pymailai[openai]

import os
from openai import OpenAI
from pymailai import EmailAgent, EmailConfig
from pymailai.message import EmailData

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

async def process_with_openai(message: EmailData) -> Optional[EmailData]:
    completion = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": message.body_text}
        ]
    )

    return EmailData(
        message_id="",
        subject=f"Re: {message.subject}",
        from_address=message.to_addresses[0],
        to_addresses=[message.from_address],
        cc_addresses=[],
        body_text=completion.choices[0].message.content,
        body_html=None,
        timestamp=message.timestamp,
        in_reply_to=message.message_id,
        references=[message.message_id]
    )

Anthropic Example

pip install pymailai[anthropic]

import anthropic
from pymailai import EmailAgent, EmailConfig
from pymailai.message import EmailData

client = anthropic.AsyncAnthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

async def process_with_anthropic(message: EmailData) -> Optional[EmailData]:
    message_content = await client.messages.create(
        model="claude-3-opus-20240229",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": message.body_text}
        ]
    )

    return EmailData(
        message_id="",
        subject=f"Re: {message.subject}",
        from_address=message.to_addresses[0],
        to_addresses=[message.from_address],
        cc_addresses=[],
        body_text=message_content.content[0].text,
        body_html=None,
        timestamp=message.timestamp,
        in_reply_to=message.message_id,
        references=[message.message_id]
    )

Ollama Example

pip install pymailai[ollama]

from ollama import chat, ChatResponse
from pymailai import EmailAgent, EmailConfig
from pymailai.message import EmailData

async def process_with_ollama(message: EmailData) -> Optional[EmailData]:
    response: ChatResponse = chat(
        model="llama3.2",  # Latest Llama version
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": message.body_text}
        ]
    )

    return EmailData(
        message_id="",
        subject=f"Re: {message.subject}",
        from_address=message.to_addresses[0],
        to_addresses=[message.from_address],
        cc_addresses=[],
        body_text=response.message.content,
        body_html=None,
        timestamp=message.timestamp,
        in_reply_to=message.message_id,
        references=[message.message_id]
    )

Next Steps