Send Email

Send emails with one line of code. No config, no complexity.

Usage

Option 1: Import directly

from connectonion import send_email

agent = Agent("assistant", tools=[send_email])

Option 2: Copy and customize

Terminalbash

$co copy send_email

from tools.send_email import send_email  # Your local copy

Quick Debug

Email not working? Try this:

# 1. Check if email is activated
grep IS_EMAIL_ACTIVE ~/.co/keys.env
# If false, run: co auth

# 2. Test directly
python -c "from connectonion import send_email; print(send_email('your@email.com', 'Test', 'It works!'))"

# 3. Common fixes
co auth  # Refresh token if expired
co init  # If missing .co directory

Quick Start

30 seconds to first email

One line. That's it.

from connectonion import send_email

send_email("alice@example.com", "Welcome!", "Thanks for joining us!")

Run it:

Code

>>> send_email("alice@example.com", "Welcome!", "Thanks for joining us!")

Result

{'success': True, 'message_id': 'msg_123', 'from': '0x1234abcd@mail.openonion.ai'}

Email sent. Done.

Core Concept

What you get:

Simple function

send_email(to, subject, message)

Zero configuration

No API keys to manage

Your own email

Unique address for every agent

Professional delivery

Good reputation & reliability

The function signature

def send_email(to: str, subject: str, message: str) -> dict:
    """Send an email. Returns success/failure."""

Three parameters. Nothing else.

Examples

Basic notification

Code

send_email("user@example.com", "Order shipped", "Track it: ABC123")

Result

{'success': True, 'message_id': 'msg_124'}

Verification code

Code

send_email("bob@example.com", "Your code: 456789", "Verify your account")

Result

{'success': True, 'message_id': 'msg_125'}

Status update

Code

send_email("team@example.com", "Build passed", "All tests green")

Result

{'success': True, 'message_id': 'msg_126'}

HTML content (automatic)

Code

send_email(
    "alice@example.com",
    "Weekly Report",
    "<h1>Progress</h1><p>3 features shipped!</p>"
)

Result

{'success': True, 'message_id': 'msg_127'}

Your Email Address

Every agent automatically gets an email address:

0x1234abcd@mail.openonion.ai

•Based on your public key (first 10 characters)

•Professional domain with good reputation

•Generated during co init

•Activated with co auth

Check your email address

Your email is configured in ~/.co/keys.env:

AGENT_EMAIL=0x04e1c4ae@mail.openonion.ai
IS_EMAIL_ACTIVE=true  # Set to true after 'co auth'

Email Activation Lifecycle

Generated

Email address created during co init

Activation Prompt

You'll be asked to activate your agent's email

Active

Email is fully functional after authentication

Two ways to activate:

Option 1: Immediate activation (recommended)

Terminalbash

$co init

Agent email: 0x1234abcd@mail.openonion.ai (inactive) Your agent can send emails! Would you like to activate your agent's email now? [Y/n]: y Email activated! Your agent can now send emails.

Option 2: Activate later

Terminalbash

$co auth

Want a custom name?

Upgrade to a custom email for $0.99:

mybot@mail.openonion.ai

ai-assistant@mail.openonion.ai

support@mail.openonion.ai

Return Values

✓ Success

{
    'success': True,
    'message_id': 'msg_123',
    'from': '0x1234abcd@mail.openonion.ai'  # Your agent's email
}

✗ Failure

{
    'success': False,
    'error': 'Rate limit exceeded'
}

Common errors:

•"Rate limit exceeded" - Hit your quota
•"Invalid email address" - Check the recipient
•"Authentication failed" - Token expired, run co auth
•"Email not activated" - Run co auth to activate
•"Not in a ConnectOnion project" - Run co init first

Using with an Agent

Give your agent the ability to send emails:

from connectonion import Agent, send_email

# Create an agent with email capability
agent = Agent(
    "customer_support",
    tools=[send_email],
    instructions="You help users and send them email confirmations"
)

# The agent can now send emails autonomously
response = agent("Send a welcome email to alice@example.com")
# Agent sends: send_email("alice@example.com", "Welcome!", "Thanks for joining...")

Real-world monitoring example

from connectonion import Agent, send_email
import time

def check_system_status() -> dict:
    """Check if the system is running properly."""
    cpu_usage = 95  # Simulated high CPU
    return {"status": "warning", "cpu": cpu_usage}

# Create monitoring agent
monitor = Agent(
    "system_monitor",
    tools=[check_system_status, send_email],
    instructions="Monitor system health and alert admin@example.com if issues"
)

# Agent checks system and sends alerts
monitor("Check the system and alert if there are problems")
# Agent will:
# 1. Call check_system_status() 
# 2. See high CPU (95%)
# 3. Call send_email("admin@example.com", "Alert: High CPU", "CPU at 95%...")

Complete Example

Here's a real-world example sending different types of emails:

from connectonion import send_email

# Welcome email
result = send_email(
    "new_user@example.com",
    "Welcome to our platform!",
    "We're excited to have you. Check out our docs to get started."
)
print(f"Welcome email: {result['success']}")

# Alert notification
result = send_email(
    "admin@example.com",
    "🚨 High CPU usage detected",
    "Server CPU at 95% for the last 5 minutes"
)
print(f"Alert sent: {result['success']}")

# Daily report with HTML
result = send_email(
    "team@example.com",
    "Daily Summary",
    """
    <h2>Today's Metrics</h2>
    <ul>
        <li>Users: 1,234</li>
        <li>Revenue: $5,678</li>
        <li>Uptime: 99.9%</li>
    </ul>
    """
)
print(f"Report sent: {result['success']}")

The Details

Quotas

Free tier:100 emails/month
Plus tier:10,000 emails/month
Pro tier:50,000 emails/month

Rate Limiting

Automatic rate limiting prevents abuse:

•Returns error on limit exceeded
•Resets monthly
•No configuration needed

Content Types

•
Plain text
Just send a string
•
HTML
Auto-detected from tags
•
Mixed
HTML with plain fallback

From Address

Free tier:
0x{key_prefix}@mail.openonion.ai
Custom name:
yourname@mail.openonion.ai

Behind the Scenes

•Email configured during co init

•Stored in ~/.co/keys.env

•Uses Resend API for delivery

•Automatic retry on failures

•Logs all emails for debugging

•SPF/DKIM configured

Troubleshooting

Check activation status

grep IS_EMAIL_ACTIVE ~/.co/keys.env
# Should show: IS_EMAIL_ACTIVE=true

If false, run co auth to activate.

Check for errors

result = send_email("test@example.com", "Test", "Testing")
if not result['success']:
    print(f"Error: {result['error']}")

Debug mode

See what's happening under the hood:

import os
os.environ['CONNECTONION_DEBUG'] = '1'

from connectonion import send_email
result = send_email("test@example.com", "Debug Test", "Testing with debug")
# Will show detailed API calls and responses

Check quota

from connectonion import get_agent_info
info = get_agent_info()
print(f"Email quota: {info.get('email_quota_remaining', 'Unknown')} remaining")

Philosophy

One function, one purpose: Send an email

No templates to learn. No configuration files. No complex APIs.

Just send_email(to, subject, message).

Keep simple things simple.

Send Email

Usage

Quick Debug

Quick Start

Core Concept

What you get:

The function signature

Examples

Basic notification

Verification code

Status update

HTML content (automatic)

Your Email Address

Check your email address

Email Activation Lifecycle

Two ways to activate:

Want a custom name?

Return Values

✓ Success

✗ Failure

Common errors:

Using with an Agent

Real-world monitoring example

Complete Example

The Details

Quotas

Rate Limiting

Content Types

From Address

Behind the Scenes

Troubleshooting

Check activation status

Check for errors

Debug mode

Check quota

Philosophy

Star us on GitHub