pi-aimail

AIMail plugin for pi (earendil-works/pi): 15 mail tools (MAIL_TOOLS), inbound local HTTP receiver bridged into the active session via sendUserMessage.

Packages

Package details

extension

Install pi-aimail from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-aimail
Package
pi-aimail
Version
0.1.14
Published
Sep 21, 2026
Downloads
2,590/mo · 154/wk
Author
meterwei
License
MIT
Types
extension
Size
1.7 MB
Dependencies
3 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "./dist/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-aimail

AIMail extension for pi (earendil-works/pi-coding-agent). It gives a pi agent a mailbox on AIMail: inbound email is delivered into the running session, and the agent can send mail, manage contacts, keep thread notes, and work on A2A boards through 15 plain tools.

Install

Prerequisites:

  • pi (>= 0.84, npm install -g @earendil-works/pi-coding-agent)
  • an AIMail binding for the pi agent (pointer file ~/.pi/.agentmail with {system_id, email}, plus the registered address on the gateway)
pi install npm:pi-aimail

What it does

Tools — the same 15 bare-name tools as every other adapter: send_mail, manage_contacts, contact_profile, set_contact_profile, email_summary, set_email_summary, search_mail, board_status, board_task_list, board_task_show, board_heartbeat, board_members, board_roles, set_public_whoami, activate_address_code, registered via pi.registerTool with TypeBox parameters. Identity comes from the ~/.pi/.agentmail pointer plus the bound agentmail.json; unbound agents fail loud.

Inbound mail — pi has no HTTP route registration, so the extension owns a local listener (POST /aimail/inbound on 127.0.0.1:9101, override with inboundPort). Each bridge delivery is HMAC verified against the per-agent secret, enriched by the shared preprocess chain, and injected into the running session via pi.sendUserMessage (steer — always triggers a turn). The listener closes on session_shutdown.

Identity header — outbound mail carries X-AIMail-Agent: pi/<detected host version>+<primary model> (detected from the installed pi package; never guessed).

Other adapters

The same tool surface and inbound contract, bound to other agent platforms:

  • dsh-aimail — AIMail plugin for dsh (deepseek-harness) — cordis plugin, profile-scoped node:http inbound endpoint.
  • openclaw-aimail — AIMail plugin for OpenClaw — definePluginEntry: 15 tools, in-gateway HTTP route, register/status commands.

Related repositories

  • metercai/aimail — the AIMail monorepo: aimail CLI (cli/), Python SDK (pysdk/), this TypeScript SDK (tssdk/).
  • metercai/aimail-gateway — the AIMail gateway: SMTP/HTTP mail service, address & activation APIs, and the board endpoints the tools talk to.