DeltaChat Plugin for Agent Zero

Agent Zero plugin for DeltaChat messaging integration. Uses official DeltaChat RPC components to send and receive messages, manage contacts, and run an event-based daemon with HTTP API.

Quick Start

# Deploy plugin to usr/plugins/
./deploy.sh

# Install and start daemon
bash scripts/deltachat-supervisord.sh install
bash scripts/deltachat-supervisord.sh start

# Onboard a DeltaChat account
python scripts/deltachat_onboard.py --qr /path/to/qr-code.png
# or: python scripts/deltachat_onboard.py --link "dcaccount:https://..."

# Verify installation
bash scripts/deltachat-check.sh

Requires deltachat-rpc-server and deltachat-rpc-client (installed automatically via hooks.py).

Key Directories

Directory	Purpose
config/	Central path constants and runtime configuration
scripts/	Daemon, CLI, API server, onboarding, and utility scripts
scripts/cli/	Unified CLI command implementations
scripts/api/	FastAPI HTTP server (routes, schemas, middleware)
scripts/api/routes/	API route modules (accounts, contacts, messages, queue, webxdc)
tools/	Agent Zero native tool (HTTP API client)
prompts/	Tool prompt documentation for agent system
helpers/	Shared helper modules

Key Files

• plugin.yaml - Plugin manifest (name, version, dependencies)
• hooks.py - Install/uninstall hooks (apt + pip deps into framework venv)
• deploy.sh - Build, deploy, validate, and zip script
• config/paths.py - Central path constants (SKILL_DIR, ACCOUNTS_DIR, QUEUE_DB_PATH)
• tools/deltachat.py - Agent Zero native tool (HTTP client to daemon API on localhost:8765)
• scripts/deltachat_daemon.py - Event-based daemon (RPC listener + SQLite queue + HTTP API)
• scripts/deltachat - Unified CLI entry point (argparse-based)
• scripts/deltachat_onboard.py - Account onboarding via QR code or dcaccount link
• scripts/deltachat-supervisord.sh - Supervisord service install, start, stop, check
• scripts/api/account_manager.py - AccountManager singleton (SQLite + TOML sync)
• scripts/api/dependencies.py - DB path, queue manager, account manager singletons
• scripts/api/routes/webxdc.py - Webxdc app interaction endpoints (info, updates, send, apps)

Tech Stack

Python 3.12+ | FastAPI | uvicorn | SQLite | deltachat-rpc-client | deltachat-rpc-server | pyzbar | Pillow

Architecture

Agent Zero -> tools/deltachat.py -> HTTP API (localhost:8765) -> daemon
                                                                |
                                                    deltachat-rpc-server -> DeltaChat Core -> SMTP/IMAP
                                                                |
                                                    SQLite queue (message IDs only)
                                                                |
                                                    webxdc status updates (payload-agnostic)

• Daemon owns the RPC lifecycle; all other components communicate via HTTP API
• HTTP API runs inside the daemon process (shared RPC, no accounts.lock conflicts)
• Queue stores only message IDs (E2EE compliant; content loaded via RPC)
• Graceful shutdown via SIGTERM (30 second timeout)

Webxdc Support

The plugin provides generic webxdc app interaction via four API endpoints:

• GET /api/v1/webxdc/{message_id}/info — App metadata (name, source code URL, summary)
• GET /api/v1/webxdc/{message_id}/updates — Status updates (app data history)
• POST /api/v1/webxdc/{message_id}/send-update — Send a status update to the app
• GET /api/v1/webxdc/apps — List all webxdc apps across all chats

The plugin is payload-agnostic: it passes JSON payloads through transparently without interpreting app-specific formats (e.g. Yjs CRDT). App-specific payload construction is a separate concern handled outside the plugin.

Notes

• Never commit accounts/, queue/, or config/account.json — these contain runtime data and credentials.
• Never call rpc.close() on the shared RPC instance or account.start_io() in API code; the daemon owns I/O.
• Never use supervisorctl restart — use stop + start to avoid spawn errors.
• See AGENTS.md for detailed guidance for AI coding agents.