Email

The EmailConnector provides email-based communication using standard SMTP/IMAP (zero external dependencies) with an optional Gmail API backend for Google Workspace environments.

See examples/alarm_to_workorder/ for a workflow that includes a notify_technician step.

Prerequisites

SMTP/IMAP (default)

• SMTP server hostname and port (e.g. smtp.gmail.com:465)
• IMAP server hostname and port (e.g. imap.gmail.com:993) — for receiving
• Email credentials (username + password or app-specific password)

Gmail API (optional)

• A Google Cloud project with Gmail API enabled
• OAuth 2.0 credentials JSON file (Desktop app type)
• Install the Gmail extra: pip install machina-ai[gmail]

Installation

# SMTP/IMAP — no extra dependencies (uses Python stdlib)
pip install machina-ai

# Gmail API backend
pip install machina-ai[gmail]

Configuration

Python (SMTP/IMAP)Python (Gmail API)YAML

from machina.connectors import Email

email = Email(
    smtp_host="smtp.gmail.com",
    smtp_port=465,
    imap_host="imap.gmail.com",
    imap_port=993,
    username="agent@example.com",
    password="app-specific-password",
)

from machina.connectors import Email

email = Email(
    gmail_credentials_file="credentials.json",
    from_address="agent@example.com",
)

connectors:
  email:
    type: email
    smtp_host: smtp.gmail.com
    smtp_port: 465
    imap_host: imap.gmail.com
    imap_port: 993
    username: ${EMAIL_USERNAME}
    password: ${EMAIL_PASSWORD}

Capabilities

Capability	Method	Description
send_message	send_message(to, text, subject=...)	Send an email
receive_message	listen(handler)	Poll IMAP inbox for new messages

Usage with Agent

from machina import Agent
from machina.connectors import Email

email = Email(
    smtp_host="smtp.example.com",
    imap_host="imap.example.com",
    username="agent@example.com",
    password="${EMAIL_PASSWORD}",
)

agent = Agent(
    llm="openai:gpt-4o",
    connectors=[email],
)
await agent.start()

Parameters

Parameter	Type	Default	Description
smtp_host	str	""	SMTP server hostname
smtp_port	int	465	SMTP server port
imap_host	str	""	IMAP server hostname (for receiving)
imap_port	int	993	IMAP server port
username	str	""	Email account username
password	str	""	Email account password
use_tls	bool	True	Use TLS/SSL (True=SMTP_SSL, False=STARTTLS)
from_address	str	username	Sender address for outgoing mail
gmail_credentials_file	str \| None	None	Path to Gmail OAuth credentials (activates Gmail API mode)
poll_interval	int	30	Seconds between inbox polls

Known Limitations

• HTML email rendering is not supported (plain text only).
• Attachments (e.g. PDF work orders) are not yet supported.
• Gmail API mode requires a one-time OAuth browser flow on first use.
• IMAP polling is not real-time — use poll_interval to control frequency.

API Reference

EmailConnector

EmailConnector(*, smtp_host: str = '', smtp_port: int = 465, imap_host: str = '', imap_port: int = 993, username: str = '', password: str = '', use_tls: bool = True, from_address: str = '', gmail_credentials_file: str | None = None, poll_interval: int = 30)

Connector for email via SMTP/IMAP or Gmail API.

Uses the Python standard library (smtplib + imaplib) by default — no extra dependencies required. For Google Workspace environments, pass gmail_credentials_file to use the Gmail API backend instead (requires pip install machina-ai[gmail]).

Parameters:

Name	Type	Description	Default
smtp_host	str	SMTP server hostname.	''
smtp_port	int	SMTP server port (default 465 for SSL).	465
imap_host	str	IMAP server hostname for receiving mail.	''
imap_port	int	IMAP server port (default 993 for SSL).	993
username	str	Email account username (usually the email address).	''
password	str	Email account password or app-specific password.	''
use_tls	bool	Whether to use TLS/SSL (default True).	True
from_address	str	The From address for outgoing mail. Defaults to username if not set.	''
gmail_credentials_file	str | None	Path to a Gmail API OAuth credentials JSON file. When set, SMTP/IMAP are ignored and the Gmail API is used instead.	None
poll_interval	int	Seconds between IMAP inbox polls (default 30).	30

Example

from machina.connectors import Email

email_conn = Email(
    smtp_host="smtp.example.com",
    imap_host="imap.example.com",
    username="agent@example.com",
    password="${EMAIL_PASSWORD}",
)
await email_conn.connect()
await email_conn.send_message("tech@example.com", "WO-2026-42 created")

connect async

connect() -> None

Establish SMTP connection or authenticate with Gmail API.

disconnect async

disconnect() -> None

Close SMTP and IMAP connections or release Gmail resources.

health_check async

health_check() -> ConnectorHealth

Check email connectivity.

send_message async

send_message(to: str, text: str, *, subject: str = 'Machina Notification') -> None

Send an email message.

Parameters:

Name	Type	Description	Default
to	str	Recipient email address.	required
text	str	Message body (plain text).	required
subject	str	Email subject line.	'Machina Notification'

Raises:

Type	Description
ConnectorError	If not connected or sending fails.

listen async

listen(handler: MessageHandler) -> None

Poll the IMAP inbox for new messages and dispatch to handler.

For Gmail API mode, polls using the Gmail API users.messages.list endpoint. For SMTP/IMAP mode, connects to the IMAP server and polls for UNSEEN messages.

This is a blocking call that polls until cancelled.

Parameters:

Name	Type	Description	Default
handler	MessageHandler	Async callback that receives an :class:IncomingMessage and returns the response text.	required