Tools

The tools package provides functionality for integrating email sending capabilities with AI models like Anthropic’s Claude and OpenAI’s GPT. The package is organized into the following modules:

  • core: Contains core email functionality (execute_query_emails, execute_send_email)

  • schemas: Contains schema definitions for different AI models (Anthropic, OpenAI, Ollama)

All functions are conveniently exposed at the package level for easy importing.

Tool Schemas

get_email_tool_schema_anthropic()

Get the email tool schema formatted for Anthropic Claude models.

Returns:

A dictionary containing the tool schema

Return type:

dict

Example usage with Gmail:

from pymailai.gmail import create_gmail_client
from pymailai.tools import get_email_tool_schema_anthropic, execute_send_email

# 1. Initialize Gmail client
gmail = await create_gmail_client()

# 2. Set up tool schema
tools = get_email_tool_schema_anthropic()

# 3. Make API call with tool
response = await client.messages.create(
    model="claude-3-opus-20240229",
    tools=tools,
    messages=[{"role": "user", "content": "Send an email..."}]
)

# 4. Execute tool calls from response
for tool_call in response.content[0].tool_calls or []:
    if tool_call.name == "send_email":
        result = await execute_send_email(
            gmail,
            to=tool_call.parameters["to"],
            subject=tool_call.parameters["subject"],
            body=tool_call.parameters["body"],
            cc=tool_call.parameters.get("cc"),
        )
        print(f"Email send result: {result}")

Example usage with IMAP/SMTP:

from pymailai.config import EmailConfig
from pymailai.client import EmailClient
from pymailai.tools import get_email_tool_schema_anthropic, execute_send_email

# 1. Initialize IMAP/SMTP client
config = EmailConfig(
    email="your-email@example.com",
    password="your-password",
    imap_server="imap.example.com",
    smtp_server="smtp.example.com",
    imap_port=993,  # Default SSL/TLS port
    smtp_port=465,  # Default SSL/TLS port
)
email_client = EmailClient(config)

# 2. Set up tool schema
tools = get_email_tool_schema_anthropic()

# 3. Make API call with tool
response = await client.messages.create(
    model="claude-3-opus-20240229",
    tools=tools,
    messages=[{"role": "user", "content": "Send an email..."}]
)

# 4. Execute tool calls from response
for tool_call in response.content[0].tool_calls or []:
    if tool_call.name == "send_email":
        result = await execute_send_email(
            email_client,
            to=tool_call.parameters["to"],
            subject=tool_call.parameters["subject"],
            body=tool_call.parameters["body"],
            cc=tool_call.parameters.get("cc"),
        )
        print(f"Email send result: {result}")
get_email_tool_schema_openai()

Get the email tool schema formatted for OpenAI GPT models.

Returns:

A dictionary containing the tool schema

Return type:

dict

Example usage with Gmail:

from pymailai.gmail import create_gmail_client
from pymailai.tools import get_email_tool_schema_openai, execute_send_email

# 1. Initialize Gmail client
gmail = await create_gmail_client()

# 2. Set up tool schema
tools = get_email_tool_schema_openai()

# 3. Make API call with tool
completion = await client.chat.completions.create(
    model="gpt-4",
    tools=tools,
    messages=[{"role": "user", "content": "Send an email..."}]
)

# 4. Execute tool calls from response
for tool_call in completion.choices[0].message.tool_calls or []:
    if tool_call.function.name == "send_email":
        result = await execute_send_email(
            gmail,
            to=tool_call.function.arguments["to"],
            subject=tool_call.function.arguments["subject"],
            body=tool_call.function.arguments["body"],
            cc=tool_call.function.arguments.get("cc"),
        )
        print(f"Email send result: {result}")

Example usage with IMAP/SMTP:

from pymailai.config import EmailConfig
from pymailai.client import EmailClient
from pymailai.tools import get_email_tool_schema_openai, execute_send_email

# 1. Initialize IMAP/SMTP client
config = EmailConfig(
    email="your-email@example.com",
    password="your-password",
    imap_server="imap.example.com",
    smtp_server="smtp.example.com",
)
email_client = EmailClient(config)

# Rest of the code is the same as Gmail example...
get_email_tool_schema_ollama()

Get the email tool schema formatted for Ollama models.

Returns:

A dictionary containing the tool schema

Return type:

dict

Example usage with Gmail:

from pymailai.gmail import create_gmail_client
from pymailai.tools import get_email_tool_schema_ollama, execute_send_email

# 1. Initialize Gmail client
gmail = await create_gmail_client()

# 2. Set up tool schema
tools = get_email_tool_schema_ollama()

# 3. Make API call with tool
response = ollama.chat(
    model="llama3.1",
    tools=tools,
    messages=[{"role": "user", "content": "Send an email..."}]
)

# 4. Execute tool calls from response
for tool_call in response["message"].get("tool_calls", []):
    if tool_call["function"]["name"] == "send_email":
        result = await execute_send_email(
            gmail,
            to=tool_call["function"]["arguments"]["to"],
            subject=tool_call["function"]["arguments"]["subject"],
            body=tool_call["function"]["arguments"]["body"],
            cc=tool_call["function"]["arguments"].get("cc"),
        )
        print(f"Email send result: {result}")

Example usage with IMAP/SMTP:

from pymailai.config import EmailConfig
from pymailai.client import EmailClient
from pymailai.tools import get_email_tool_schema_ollama, execute_send_email

# 1. Initialize IMAP/SMTP client
config = EmailConfig(
    email="your-email@example.com",
    password="your-password",
    imap_server="imap.example.com",
    smtp_server="smtp.example.com",
)
email_client = EmailClient(config)

# Rest of the code is the same as Gmail example...

Tool Execution

execute_send_email(client, to, subject, body, cc=None)

Execute the send_email tool using the provided email client.

Parameters:

  • client (BaseEmailClient) – Email client instance to use for sending

  • to (List[str]) – List of recipient email addresses

  • subject (str) – Email subject line

  • body (str) – Email body content (supports markdown formatting)

  • cc (Optional[List[str]]) – Optional list of CC recipients

Returns:

Dictionary containing success status and any error message

Return type:

Dict[str, Union[bool, str]]

Example usage with Gmail:

from pymailai.tools import execute_send_email
from pymailai.gmail import create_gmail_client

# Initialize Gmail client
gmail = await create_gmail_client()

# Send email
result = await execute_send_email(
    gmail,
    to=["recipient@example.com"],
    subject="Test Email",
    body="Hello from PyMailAI!",
    cc=["cc@example.com"]
)
print(f"Email send result: {result}")

Example usage with IMAP/SMTP:

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

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

# Send email
result = await execute_send_email(
    email_client,
    to=["recipient@example.com"],
    subject="Test Email",
    body="Hello from PyMailAI!",
    cc=["cc@example.com"]
)
print(f"Email send result: {result}")

Using the Email Tool

The process of using the email tool involves four main steps:

  1. Initialize the Email Client: You can use either Gmail API or standard IMAP/SMTP:

    Gmail API: .. code-block:: python

    from pymailai.gmail import create_gmail_client gmail = await create_gmail_client()

    IMAP/SMTP: .. code-block:: python

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

    config = EmailConfig(

    email=”your-email@example.com”, password=”your-password”, imap_server=”imap.example.com”, smtp_server=”smtp.example.com”,

    ) email_client = EmailClient(config)

  2. Set up the Tool Schema: - Choose the appropriate schema for your AI model - Add it to the tools list in your API call

  3. Make the API Call: - Include the tool schema in your model request - The model will generate tool calls in its response

  4. Execute the Tool Calls: - Process the tool calls from the model’s response - Use execute_send_email() to actually send the emails - Handle the results appropriately

Tool Schema Format

The email tool schema includes the following fields:

  • to (required): List of recipient email addresses

  • subject (required): Email subject line

  • body (required): Email body content (supports markdown formatting)

  • cc (optional): List of CC recipients

For both Anthropic and OpenAI models, the schema follows their respective formats while maintaining consistent functionality.