email-skill

This skill provides script-based email operations for an agent. It includes functionalities for managing mailboxes, reading/searching emails, sending/replying/forwarding emails, and managing attachments, allowing agents to perform comprehensive email-related tasks programmatically.

Features

• IMAP operations: Read, list, mark, move, delete, copy emails
• SMTP operations: Send, reply, forward emails with attachments
• Folder management: Create, delete, rename, list mailboxes
• Dual-format bodies: Supports both plain-text and HTML, with automatic fallback generation
• Attachment handling: Supports base64-encoded attachments
• Multi-account support: Configure multiple accounts
• Authentication: Password or OAuth2 via environment variables (auto-detected)
• Signatures: Automatic signature appending to outgoing emails
• Thread support: Proper In-Reply-To and References header handling

When to use

Use this skill when you need an agent to:

• Check inbox for new emails and summarize them
• Read specific emails and extract content
• Send new emails with attachments
• Reply to or forward emails
• Organize emails by moving/copying between folders
• Create or manage mailbox folders
• Mark emails as read/unread, flagged, spam, or junk

Requirements

• Python 3.11+
• IMAP/SMTP access to your email provider
• Network access to email servers

Configuration

Basic Setup

Configure this skill with ./scripts/config.toml:

1. Copy scripts/config.default.toml to scripts/config.toml
2. Edit config.toml - fill in email address and server addresses

Authentication Setup

Authentication is automatically detected from environment variables. OAuth2 takes priority over password.

Password-based authentication:

# Linux/Mac
export EMAIL_USERNAME="me"
export EMAIL_PASSWORD="my-password"

# Windows (PowerShell)
$env:EMAIL_USERNAME="me"
$env:EMAIL_PASSWORD="my-password"

# Windows (CMD)
set EMAIL_USERNAME=me
set EMAIL_PASSWORD=my-password

OAuth2 authentication:

# Linux/Mac
export EMAIL_OAUTH2_CLIENT_ID="xxx"
export EMAIL_OAUTH2_CLIENT_SECRET="xxx"
export EMAIL_OAUTH2_REFRESH_TOKEN="xxx"
export EMAIL_OAUTH2_TOKEN_URL="https://oauth2.example.com/token"

# Windows (PowerShell)
$env:EMAIL_OAUTH2_CLIENT_ID="xxx"
$env:EMAIL_OAUTH2_CLIENT_SECRET="xxx"
$env:EMAIL_OAUTH2_REFRESH_TOKEN="xxx"
$env:EMAIL_OAUTH2_TOKEN_URL="https://oauth2.example.com/token"

# Windows (CMD)
set EMAIL_OAUTH2_CLIENT_ID=xxx
set EMAIL_OAUTH2_CLIENT_SECRET=xxx
set EMAIL_OAUTH2_REFRESH_TOKEN=xxx
set EMAIL_OAUTH2_TOKEN_URL="https://oauth2.example.com/token"

Test

# Linux/Mac
echo '{"requestId":"test","schemaVersion":"1.0","data":{"maxResults":5}}' | python3 scripts/mail_list.py

# Windows (PowerShell)
echo '{"requestId":"test","schemaVersion":"1.0","data":{"maxResults":5}}' | python scripts/mail_list.py

# Windows (CMD)
echo "{\"requestId\":\"test\",\"schemaVersion\":\"1.0\",\"data\":{\"maxResults\":5}}" | python scripts/mail_list.py

Data Exchange Contract

Overview

All scripts follow the same JSON-over-stdin contract:

1. Agent sends one JSON object to stdin
2. Script writes one JSON object to stdout
3. Logs and diagnostics are written to stderr

Request Schema

{
  "requestId": "optional-trace-id",
  "schemaVersion": "1.0",
  "account": "optional-account-name-in-config",
  "data": {}
}

Success Response Schema

{
  "ok": true,
  "requestId": "same-as-request",
  "schemaVersion": "1.0",
  "data": {}
}

Error Response Schema

{
  "ok": false,
  "requestId": "same-as-request",
  "schemaVersion": "1.0",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Scripts

folder_create.py

Create mailbox folder.

folder_delete.py

Delete mailbox folder.

folder_list.py

List mailbox folders.

folder_rename.py

Rename mailbox folder.

mail_copy.py

Copy email(s) between folders.

mail_delete.py

Delete email(s).

mail_forward.py

Forward email with optional additions.

Automatically includes original email and attachments.

mail_mark.py

Mark email(s) with flags.

mail_move.py

Move email(s) between folders.

mail_read.py

Read email content and metadata.

Marks message as read after fetch.

mail_reply.py

Reply to email.

mail_list.py

List emails using IMAP search.

mail_send.py

Send new email.

Examples

List new emails

echo '{"requestId":"test","schemaVersion":"1.0","data":{"maxResults":10}}' | python3 scripts/mail_list.py

Read email by UID

{ "requestId": "read", "schemaVersion": "1.0", "data": { "uid": "123" } }

Search from sender

{
  "requestId": "search",
  "schemaVersion": "1.0",
  "data": { "query": "FROM [email protected]" }
}

Send email

{
  "requestId": "send",
  "schemaVersion": "1.0",
  "data": {
    "to": ["[email protected]"],
    "subject": "Hello",
    "bodyText": "Hello world!"
  }
}

Reply to email

{
  "requestId": "reply",
  "schemaVersion": "1.0",
  "data": { "uid": "123", "bodyText": "Thanks!" }
}

Mark and move

{"requestId":"mark","schemaVersion":"1.0","data":{"uids":"123","markType":"read"}}
{"requestId":"move","schemaVersion":"1.0","data":{"uids":"123","targetFolder":"Archive"}}

Troubleshooting

AUTH_ERROR

• Ensure environment variables are set correctly
• For 2FA accounts, use app password (EMAILAPPPASSWORD)
• OAuth2 requires all four EMAILOAUTH2* variables

NETWORK_ERROR

• Verify IMAP port 993 (SSL) or 143 (STARTTLS)
• Verify SMTP port 465 (SSL) or 587 (STARTTLS)
• Check firewall settings

CONFIG_ERROR

• Ensure config.toml exists and is valid TOML
• Check email, imap.host, smtp.host are configured

Security Warnings

⚠️ SSL Verification: Setting ssl_verify = false in config disables certificate validation and exposes connections to man-in-the-middle attacks. Only disable for local development/testing.

⚠️ IMAP Injection Protection: User-provided search queries are validated against a whitelist of safe commands. Custom queries containing ()"; characters will be rejected.

Debugging

Check stderr for detailed error logs with code, message, and details.