packet-pigeon

Packet Pigeon — Email capabilities for AI agents — receive, read, reply, and send through MCP.

How it works

Sender ─▶ Email Routing ─▶ Worker email() ─▶ R2 raw.eml
                                              ─▶ Queue ─▶ Worker queue() ─▶ R2 parsed output

• email() streams message.raw straight to R2 with FixedLengthStream(message.rawSize), tagging it with emailId (UUIDv7), envelope from/to, and receipt timestamp. Nothing is parsed on the hot path.

• R2 object-creation notifications are forwarded to the packet-pigeon-email-parse queue.

• queue() re-reads the .eml from R2, parses it with postal-mime, and writes the extracted HTML body and attachments back to R2.

Related MCP server: InboxAPI CLI

Storage layout

emails/
└── {emailId}/
    ├── raw.eml
    ├── body.html                  # only when the message has an HTML part
    └── attachments/
        └── {ordinal}/{filename}

raw.eml carries emailId, envelopeFrom, envelopeTo, and workerReceivedAt as R2 custom metadata. Attachment filenames are sanitized (/ \ : * ? " < > | and control chars become _); a missing filename falls back to untitled.

Deployment & configuration

Required: an R2 bucket (packet-pigeon), a queue (packet-pigeon-email-parse) wired to R2 event notifications, and an Email Routing address pointing at the Worker (e.g. ai@agent.asyncat.app).

npm install
npm run deploy

Development

Requirements: Node.js 22+ and a logged-in Wrangler CLI.

npm install
npm run dev