API Reference

Core Modules

Main Application

MailOS Web Application Module.

This module provides a web interface for managing email monitoring configurations using PyWebIO.

class mailos.app.CheckerConfig(id: str, name: str, monitor_email: str, password: str, imap_server: str, imap_port: int, llm_provider: str, model: str, system_prompt: str, enabled_tools: List[str], enabled: bool, auto_reply: bool, last_run: str = 'Never')[source]

Bases: object

Email checker configuration.

id: str
name: str
monitor_email: str
password: str
imap_server: str
imap_port: int
llm_provider: str
model: str
system_prompt: str
enabled_tools: List[str]
enabled: bool
auto_reply: bool
last_run: str = 'Never'
classmethod from_form(checker_id: str | None = None) CheckerConfig[source]

Create CheckerConfig from form data.

to_dict() Dict[source]

Convert to dictionary for storage.

__init__(id: str, name: str, monitor_email: str, password: str, imap_server: str, imap_port: int, llm_provider: str, model: str, system_prompt: str, enabled_tools: List[str], enabled: bool, auto_reply: bool, last_run: str = 'Never') None
mailos.app.update_vendor_credentials(checker_dict: Dict, vendor_config) None[source]

Update vendor-specific credentials in checker dictionary.

mailos.app.save_checker(identifier: str | None = None) None[source]

Save or update an email checker configuration.

mailos.app.ensure_checker_ids(config: Dict) bool[source]

Ensure all checkers have IDs.

mailos.app.check_email_app()[source]

Run the main web application.

mailos.app.cli()[source]

CLI entry point for the application.

Email Processing

Email checking functions.

mailos.check_emails.check_emails(checker_config)[source]

Check emails for a given checker configuration.

mailos.check_emails.main()[source]

Check emails for all enabled checkers.

mailos.check_emails.init_scheduler()[source]

Initialize the scheduler for email checking.

Email reply handling and processing module.

This module contains functions for handling email replies, including: - Creating prompts for LLM responses - Processing email attachments - Sending automated replies using configured LLM providers

class mailos.reply.EmailData(sender: str, subject: str, body: str = '', msg_date: str = '', message_id: str = '', attachments: List[Dict[str, Any]] = None)[source]

Bases: object

Structure for validated email data.

sender: str
subject: str
body: str = ''
msg_date: str = ''
message_id: str = ''
attachments: List[Dict[str, Any]] = None
classmethod from_dict(data: Dict[str, Any]) EmailData[source]

Create EmailData instance from dictionary.

__init__(sender: str, subject: str, body: str = '', msg_date: str = '', message_id: str = '', attachments: List[Dict[str, Any]] = None) None
mailos.reply.create_email_prompt(email_data: EmailData, available_tools: List[Any], has_images: bool = False) str[source]

Create a prompt for the LLM based on the email data.

Parameters:
  • email_data – Structured email data

  • available_tools – List of available tools for the LLM

  • has_images – Whether the email contains image attachments

Returns:

Formatted prompt string for the LLM

mailos.reply.process_attachments(attachments: List[Dict[str, Any]]) List[Content][source]

Process email attachments and convert images to Content objects.

Parameters:

attachments – List of attachment dictionaries

Returns:

List of Content objects for valid images

mailos.reply.handle_email_reply(checker_config: Dict[str, Any], email_data: Dict[str, Any]) bool[source]

Handle the email reply process using the configured LLM.

Parameters:
  • checker_config – Configuration for the email checker

  • email_data – Dictionary containing email information

Returns:

True if reply was sent successfully, False otherwise

Return type:

bool

User Interface

UI functions for creating and editing checker forms.

mailos.ui.checker_form.create_checker_form(checker_id=None, on_save=None)[source]

Create a form for new checker or editing existing one.

Parameters:
  • checker_id – The ID of the checker to edit, or None for new checker

  • on_save – Callback function to save the checker

UI functions for displaying the checker list.

mailos.ui.checker_list.display_checker_controls(on_control, on_filter=None)[source]

Display the top control buttons.

mailos.ui.checker_list.display_checker(checker, action_callback, status_filter=None)[source]

Display a single checker with its controls.

UI display functions.

mailos.ui.display.display_checkers(config, save_checker=None)[source]

Display configured email checkers.

mailos.ui.display.refresh_display(save_checker=None)[source]

Refresh the display of configured email checkers.

LLM Integration

MailOS LLM Factory Module.

This module provides a factory pattern implementation for creating Language Learning Model (LLM) instancesfrom different providers. It supports multiple LLM providers and handles their specific initialization requirements.

Supported Providers:
  • OpenAI

  • Anthropic

  • Bedrock Anthropic (AWS)

Example

llm = LLMFactory.create(

provider=’openai’, model=’gpt-4’, api_key=’your-api-key’

)

# For AWS Bedrock: llm = LLMFactory.create(

provider=’bedrock-anthropic’, model=’claude-v2’, aws_access_key=’key’, aws_secret_key=’secret’, aws_region=’us-east-1’

)

class mailos.vendors.factory.LLMFactory[source]

Bases: object

Factory for creating LLM instances.

classmethod register(name: str, provider_class)[source]

Register a new LLM provider.

classmethod create(provider: str, model: str, **kwargs)[source]

Create an LLM instance.

Parameters:
  • provider – The name of the provider (e.g., ‘openai’, ‘anthropic’,

  • 'bedrock-anthropic')

  • model – The model name to use

  • **kwargs – Additional arguments passed to the provider constructor (e.g., api_key, aws_access_key, aws_secret_key, etc.)

Data models for vendor integrations and LLM interactions.

class mailos.vendors.models.RoleType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Enumeration of possible message role types.

SYSTEM = 'system'
USER = 'user'
ASSISTANT = 'assistant'
FUNCTION = 'function'
class mailos.vendors.models.ContentType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Enumeration of supported content types.

TEXT = 'text'
IMAGE = 'image'
AUDIO = 'audio'
FILE = 'file'
EMBEDDING = 'embedding'
class mailos.vendors.models.Content(type: ContentType, data: Any, mime_type: str | None = None)[source]

Bases: object

Represents content in a message with type and value.

type: ContentType
data: Any
mime_type: str | None = None
to_dict() Dict[source]

Convert content to a dictionary.

__init__(type: ContentType, data: Any, mime_type: str | None = None) None
class mailos.vendors.models.Message(role: RoleType, content: List[Content], name: str | None = None, function_call: Dict | None = None, timestamp: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 730718))[source]

Bases: object

Represents a message in a conversation with role and content.

role: RoleType
content: List[Content]
name: str | None = None
function_call: Dict | None = None
timestamp: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 730718)
to_dict() Dict[source]

Convert message to a dictionary.

__init__(role: RoleType, content: List[Content], name: str | None = None, function_call: Dict | None = None, timestamp: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 730718)) None
class mailos.vendors.models.Tool(name: str, description: str, parameters: Dict, function: Callable, required_params: List[str] = None)[source]

Bases: object

Represents a tool or function that can be called by the LLM.

name: str
description: str
parameters: Dict
function: Callable
required_params: List[str] = None
to_dict() Dict[source]

Convert tool to a dictionary.

__init__(name: str, description: str, parameters: Dict, function: Callable, required_params: List[str] = None) None
class mailos.vendors.models.ModelConfig(temperature: float = 0.7, max_tokens: int | None = None, top_p: float = 1.0, frequency_penalty: float = 0.0, presence_penalty: float = 0.0, stop_sequences: List[str] | None = None)[source]

Bases: object

Configuration settings for LLM model behavior and parameters.

temperature: float = 0.7
max_tokens: int | None = None
top_p: float = 1.0
frequency_penalty: float = 0.0
presence_penalty: float = 0.0
stop_sequences: List[str] | None = None
__init__(temperature: float = 0.7, max_tokens: int | None = None, top_p: float = 1.0, frequency_penalty: float = 0.0, presence_penalty: float = 0.0, stop_sequences: List[str] | None = None) None
class mailos.vendors.models.LLMResponse(content: List[Content], role: RoleType = RoleType.ASSISTANT, finish_reason: str | None = None, tool_calls: List[Dict] | None = None, usage: Dict[str, int] | None = None, model: str | None = None, system_fingerprint: str | None = None, created_at: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 731484))[source]

Bases: object

Unified response model for all LLM providers.

content: List[Content]
role: RoleType = 'assistant'
finish_reason: str | None = None
tool_calls: List[Dict] | None = None
usage: Dict[str, int] | None = None
model: str | None = None
system_fingerprint: str | None = None
created_at: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 731484)
to_message() Message[source]

Convert response to a Message object.

to_dict() Dict[source]

Convert response to a dictionary.

__init__(content: List[Content], role: RoleType = RoleType.ASSISTANT, finish_reason: str | None = None, tool_calls: List[Dict] | None = None, usage: Dict[str, int] | None = None, model: str | None = None, system_fingerprint: str | None = None, created_at: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 731484)) None

Configuration schemas for LLM vendors.

class mailos.vendors.config.ConfigField(name: str, label: str, type: str, required: bool = True, default: str | None = None, help_text: str | None = None)[source]

Bases: object

Configuration field definition.

name: str
label: str
type: str
required: bool = True
default: str | None = None
help_text: str | None = None
__init__(name: str, label: str, type: str, required: bool = True, default: str | None = None, help_text: str | None = None) None
class mailos.vendors.config.VendorConfig(name: str, fields: List[ConfigField], default_model: str, supported_models: List[str])[source]

Bases: object

Vendor configuration schema.

name: str
fields: List[ConfigField]
default_model: str
supported_models: List[str]
__init__(name: str, fields: List[ConfigField], default_model: str, supported_models: List[str]) None

Utilities

Configuration utilities for loading and saving email configuration.

mailos.utils.config_utils.load_config() Dict[str, Any][source]

Load configuration from JSON file.

Returns:

Dictionary containing configuration settings

mailos.utils.config_utils.save_config(config: Dict[str, Any]) None[source]

Save configuration to JSON file.

Parameters:

config – Configuration dictionary to save

mailos.utils.config_utils.update_checker_field(checker_id: str, field: str, value: any) bool[source]

Update a single field of a checker by its ID.

Parameters:
  • checker_id – The ID of the checker to update

  • field – The field name to update

  • value – The new value for the field

Returns:

True if the update was successful, False otherwise

Return type:

bool

mailos.utils.config_utils.update_attachment_settings(settings: Dict[str, Any]) bool[source]

Update attachment-related settings.

Parameters:

settings – Dictionary containing attachment settings to update

Returns:

True if update was successful, False otherwise

Return type:

bool

mailos.utils.config_utils.get_attachment_settings() Dict[str, Any][source]

Get current attachment settings.

Returns:

Dictionary containing attachment settings

Logging utilities.

Reply utilities for MailOS.

mailos.utils.reply_utils.should_reply(email_data)[source]

Determine if an email should receive an auto-reply.

Tool System

See Tools API Reference for detailed documentation of the tool system and available tools.

See also