Receive Emails

Check your inbox with one line. Process emails safely. Keep it simple.

Usage

Option 1: Import directly

import.py
python
from connectonion import get_emails, mark_read

agent = Agent("assistant", tools=[get_emails, mark_read])

Option 2: Copy and customize

Terminalbash

$co copy get_emails

copy.py
python
from tools.get_emails import get_emails, mark_read  # Your local copy

Quick Start

10 seconds

quickstart.py
python
from connectonion import get_emails, send_email, mark_read

# Get your emails
emails = get_emails()

That's it. You have your emails.

Core Concept

Three functions. That's all:

core.py
python
get_emails(last=10, unread=False)  # Get emails
send_email(to, subject, message)   # Send email (already done)
mark_read(email_id)                # Mark as read after processing

Important: Emails are NOT auto-marked as read. You control when to mark them.

Setup

No configuration needed. Your agent's email is provisioned automatically:

Terminalbash

$co init

$co auth

Your agent receives emails at 0x{your_key}@mail.openonion.ai, stored in ~/.co/keys.env as AGENT_EMAIL.

Common Patterns

Check for new emails

check_new.py
python
from connectonion import get_emails, mark_read

# Get unread emails
new_emails = get_emails(unread=True)

for email in new_emails:
    print(f"New from {email['from']}: {email['subject']}")

    # Process the email
    if process_email(email):
        mark_read(email['id'])  # Only mark if processed successfully

Get latest email

latest.py
python
# Get just the most recent email
emails = get_emails(last=1)
if emails:
    latest = emails[0]
    print(f"Latest: {latest['subject']}")

Reply to emails

reply.py
python
from connectonion import get_emails, send_email, mark_read

# Check and reply pattern
for email in get_emails(unread=True):
    if "urgent" in email["subject"].lower():
        # Send reply
        send_email(
            email["from"],
            f"Re: {email['subject']}",
            "I'm on it!"
        )
        # Mark as handled
        mark_read(email['id'])

API Reference

get_emails(last=10, unread=False)

Fetch emails from your inbox.

last - Number of emails to fetch (default: 10)

unread - Only fetch unread emails (default: False)

Returns list of email dicts:

email_dict.py
python
[
    {
        'id': 'msg_123',
        'from': 'alice@example.com',
        'subject': 'Project Update',
        'message': 'The new feature is ready...',
        'timestamp': '2024-01-15T10:30:00Z',
        'read': False
    }
]

mark_read(email_id)

Mark an email as read.

email_id - The email ID from get_emails()

mark_unread(email_id)

Mark an email as unread.

email_id - The email ID from get_emails()

Email Agent Example

email_agent.py
python
from connectonion import Agent, get_emails, send_email, mark_read

def check_inbox() -> str:
    """Check inbox for new emails."""
    emails = get_emails(unread=True)
    if not emails:
        return "No new emails"
    return f"Found {len(emails)} unread emails:\n" + "\n".join(
        f"- {e['from']}: {e['subject']}" for e in emails
    )

def reply_to_email(email_id: str, message: str) -> str:
    """Reply to an email by ID."""
    emails = get_emails(last=50)
    email = next((e for e in emails if e['id'] == email_id), None)
    if not email:
        return "Email not found"

    send_email(email['from'], f"Re: {email['subject']}", message)
    mark_read(email_id)
    return f"Replied to {email['from']}"

agent = Agent(
    name="email-assistant",
    tools=[check_inbox, reply_to_email],
    system_prompt="You help manage emails. Check inbox and reply as needed."
)

agent.input("Check my inbox and summarize what's there")

Why No Auto-Mark?

The problem with auto-marking

bad.py
python
# BAD: Auto-mark on fetch
emails = get_emails(unread=True)  # Server marks as read
process_emails(emails)            # Crashes!
# Emails lost forever - marked read but not processed!

Our safe approach

good.py
python
# GOOD: Explicit marking
emails = get_emails(unread=True)  # Stays unread
process_emails(emails)            # Process them
mark_read([e['id'] for e in emails])  # Mark only after success

Need full Gmail features (labels, search, CRM)? Check out Gmail.

Philosophy

Three functions for everything email:

get_emails() - Read emails
send_email() - Send emails
mark_read() - Mark as processed

No complexity. No confusion. Just email.

Keep simple things simple.

Useful Tools

Send Email