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: you@gmail.com
  imapPassword: <app-password>
  smtpHost: smtp.gmail.com
  smtpPort: 587
  smtpSecure: false
  smtpUser: you@gmail.com
  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": "you@gmail.com",
    "password": "<app-password>"
  },
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "user": "you@gmail.com",
    "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