pi-email-client

IMAP/SMTP email client extension for the pi coding agent.

Read, search, send, move, and delete emails directly from your pi session. Credentials are stored locally in ~/.pi/email-config.json.

Installation

# Install from npm (once published)
pi install npm:@patimweb/pi-email

# Install from local path during development
pi install /path/to/pi-email-client

Quick Start

1. Configure your email account using the email_setup tool
2. Fetch recent inbox emails with email_fetch
3. Read full email bodies with email_read
4. Send emails with email_send

Example configuration for Gmail (requires an app-specific password):

email_setup:
  imapHost: imap.gmail.com
  imapPort: 993
  imapTls: true
  imapUser: [email protected]
  imapPassword: <app-password>
  smtpHost: smtp.gmail.com
  smtpPort: 587
  smtpSecure: false
  smtpUser: [email protected]
  smtpPassword: <app-password>
  fromName: Your Name

Tools

| Tool | Description | |------|-------------| | email_setup | Configure IMAP/SMTP credentials. Must be called first. | | email_status | Show current connection status and configured account. | | email_list_mailboxes | List all available IMAP folders. | | email_fetch | Fetch email headers from a mailbox (from, subject, date, flags). | | email_read | Read the full body of a specific email by UID. Can save attachments. | | email_search | Search emails with IMAP criteria (from, subject, body, date range, unseen). | | email_send | Send an email via SMTP (plain text, HTML, CC, BCC). | | email_delete | Delete an email by UID. | | email_move | Move an email to another mailbox. |

Commands

| Command | Description | |---------|-------------| | /inbox | Trigger the agent to fetch recent inbox emails. |

Configuration

Credentials are persisted to ~/.pi/email-config.json. The email_setup tool writes this file automatically. You can also create it manually:

{
  "imap": {
    "host": "imap.gmail.com",
    "port": 993,
    "tls": true,
    "user": "[email protected]",
    "password": "<app-password>"
  },
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "user": "[email protected]",
    "password": "<app-password>"
  },
  "fromName": "Your Name"
}

Architecture

The extension follows data-oriented programming principles:

• src/types.ts -- All domain data types as plain immutable interfaces. No behavior, no classes, no inheritance.
• src/config.ts -- Configuration state management and file persistence.
• src/clients/imap-client.ts -- IMAP operations. Each function opens a connection, performs work, and closes. Returns plain data.
• src/clients/smtp-client.ts -- SMTP send operations via nodemailer.
• src/formatting/formatters.ts -- Pure transformation functions that convert domain data into display strings. No side effects.
• src/tools/*.ts -- Individual pi tool definitions. Each tool is a single-responsibility module that wires clients and formatters together.
• index.ts -- Extension entry point. Loads config, registers tools, and registers commands.

Requirements

• Node.js 18+
• pi coding agent (latest)
• IMAP and SMTP access to your email provider

Supported Providers

Any email provider with standard IMAP/SMTP access works. Tested configurations:

| Provider | IMAP Host | IMAP Port | SMTP Host | SMTP Port | |----------|-----------|-----------|-----------|-----------| | Gmail | imap.gmail.com | 993 | smtp.gmail.com | 587 | | Outlook/Hotmail | outlook.office365.com | 993 | smtp-mail.outlook.com | 587 | | Yahoo | imap.mail.yahoo.com | 993 | smtp.mail.yahoo.com | 587 | | iCloud | imap.mail.me.com | 993 | smtp.mail.me.com | 587 |

Note: Gmail and many providers require app-specific passwords when 2FA is enabled.

Publishing as a pi Package

To publish this extension to the pi package catalog:

1. Ensure package.json has "keywords": ["pi-package"]
2. Ensure package.json has a "pi" section declaring extensions
3. Optionally add "image" or "video" preview URLs to the "pi" manifest
4. Publish to npm: npm publish
5. Users install with: pi install npm:@patimweb/pi-email

The package catalog auto-discovers packages with the pi-package keyword from npm.

Dependencies

• imap -- IMAP client
• mailparser -- Email parsing (RFC 2822, MIME)
• nodemailer -- SMTP client

License

MIT