DocsCLIco email

co email

Every agent gets its own email address. Send and read from it right in the terminal — no separate mail client, no Gmail OAuth.

Download

Your address is derived from your agent's identity, e.g. 0x7a9f3b2c@mail.openonion.ai. It's activated by co auth.

Quick Start

code
bash
# Check your inbox (the zero-arg default)
co email

# Send a message
co email send alice@example.com "Hello" "Thanks for trying ConnectOnion!"

# Read message #42 from the inbox list
co email read 42

That's the whole surface. Everything below is detail.

Commands

co email inbox — List received email

Terminalbash

$co email inbox

$co email inbox --last 25

$co email inbox --unread

Unread messages are marked with a green ●. The leftmost # is the email's id — pass it to co email read. Note: --unread filters the fetched page locally, so --last 10 --unread means "unread among your 10 most recent," not "your 10 most recent unread."

co email read <#> — Read one message

Terminalbash

$co email read 42

Prints the sender, subject, date, and body, then marks the message read. Reads from your 100 most recent messages — an email older than that won't be found by id yet.

co email send <to> <subject> <message> — Send

Terminalbash

$co email send bob@example.com "Hi" "Just checking in."

$co email send bob@example.com "Receipt" "<h1>Paid</h1><p>Thanks!</p>"

All three arguments are positional and required. HTML is auto-detected: if the body contains tags (<...>), it's sent as HTML, otherwise as plain text.

Customizing Your Address (paid)

The two commands below spend ConnectOnion credits. Each shows you the price or new quota first, then applies it — nothing is charged unless you opt in.

co email name — Claim a readable address

code

bash

co email name aaron          # check if aaron@openonion.ai is free + its price
co email name aaron --buy    # claim it (one-time charge from your credits)

output

✓ aaron@openonion.ai is available — $5.00 one-time, from credits

Claim it: co email name aaron --buy

Without --buy it only checks availability and prints the one-time price (returned live by the backend, so it's always current). Prices shown are illustrative — the real figure is whatever the check command prints.

co email upgrade — Raise your sending quota

code

bash

co email upgrade plus --domain mail.acme.com                  # plus, on your domain
co email upgrade pro  --domain mail.acme.com --alias support  # pro + a mailbox alias

The paid tiers (plus, pro) send from your own domain and lift the monthly quota, billed from your credits. A sending domain is required (--domain, -d) — leave it out and the upgrade is rejected before anything is charged. --alias, -a sets a mailbox alias, e.g. support → support@mail.acme.com.

Same Functions, in Your Agent

The CLI is a thin wrapper over two tool functions you can hand to any agent — so anything co email does, your agent can do too:

main.py
python
from connectonion import Agent
from connectonion.useful_tools import send_email, get_emails

agent = Agent("mailer", tools=[send_email, get_emails])
agent.input("Check my inbox and reply to anything urgent.")

Limitations & Troubleshooting

read only sees your recent 100 messages. The backend has no single-email endpoint yet.
No reply yet. To reply, copy the sender into send: co email send <their-address> "Re: ..." "...".
Long / multi-line bodies are awkward as a shell argument — quote carefully; piping a body from a file is not wired up.

• "No API key found" → run co auth.
• "AGENT_EMAIL not found" → run co auth to activate email.
• Authentication failed (401) → token expired, re-run co auth.
• Rate limit exceeded (429) → you've hit your tier's send quota; check co status.

co email

Quick Start

Commands

co email inbox — List received email

co email read <#> — Read one message

co email send <to> <subject> <message> — Send

Customizing Your Address (paid)

co email name — Claim a readable address

co email upgrade — Raise your sending quota

Same Functions, in Your Agent

Limitations & Troubleshooting

See Also

Star us on GitHub