mailCatch

Need trashmail or email for your bot ? No, you don't.

Email remains the 'lowest common denominator' communication transport and fallback. But for systems it is rubbish, and giving bots access to human mailboxes is an awful idea.

mailCatch extends basic "receive and display" trashmail functionality and adds agent/bot API access, LLM-powered skills, structured extraction and delivery options.

mailCatch is an Email API platform for agents (humans can use it too for e.g. trashmail) — IMAP ingestion, smart extraction, multiple delivery routes.

What it does

mailCatch turns any IMAP catch-all mailbox into a programmable email platform with a web UI.

• Multi-source IMAP — connect Cloudron mail, Migadu, Fastmail, or any IMAP server
• Smart extraction — automatically extracts 2FA codes, verification links, login links, unsubscribe links, sender identity, security alerts
• Agent API — REST + WebSocket stream + blocking "wait-for-email" endpoint designed for AI agents
• Skills system — markdown instruction documents sent to an LLM (OpenAI-compatible: Ollama, OpenRouter, Groq) to process, summarise, and extract from received email
• Address lifecycle — create, tag, label, set TTL in hours, expire, delete, burn addresses
• Forwarded email detection — detects original sender from forwarded emails (X-Forwarded headers, subject prefixes, body markers)
• Delivery routes — email, ntfy push notifications, RSS Atom feed, WebSocket stream
• Real-time UI — IMAP IDLE + WebSocket push, no polling; dark mode
• PostgreSQL-backed — real queries, not file scanning

Architecture

IMAP sources → ImapManager (IDLE/poll) → ExtractionEngine → PostgreSQL → API + UI
                                                                  ↓
                                                            SkillEngine (LLM)
                                                                  ↓
                                                            Deliveries (email, ntfy)
Delivery routes: email · ntfy · RSS feed · WebSocket stream

No SMTP server. No nginx. No PHP. Pure Node.js on Cloudron.

Configuration

Edit /app/data/config.json (via the in-app Settings panel or directly) to configure:

• imapSources — IMAP sources (host, port, user, password, TLS, mailbox, domains)
• sitePassword — web UI access password
• adminPassword — admin access password (config panel)
• ai — LLM provider (baseUrl, apiKey, model) — any OpenAI-compatible API
• smtp — outbound SMTP for email delivery (host, port, user, pass, from)
• ntfy — push notification config (url, topic, auth)

IMAP sources can also be managed via the API at /api/v1/sources.

API

Core endpoints

Method	Path	Description
GET	/api/v1/addresses	List addresses (active + expired, excludes deleted)
GET	/api/v1/addresses-all	List ALL addresses including deleted (audit page)
POST	/api/v1/addresses	Create/register an address
GET	/api/v1/addresses/:email	Get address metadata
PATCH	/api/v1/addresses/:email	Update address (label, tags, TTL, notes)
DELETE	/api/v1/addresses/:email	Delete address and all its messages
GET	/api/v1/addresses/:email/messages	List messages for an address
GET	/api/v1/addresses/:email/messages/latest	Get latest message
GET	/api/v1/messages/:id	Get full message + extracted data + attachments
DELETE	/api/v1/messages/:id	Delete a single message
GET	/api/v1/addresses/:email/wait	Wait for email (blocks until received, or timeout)
WS	/api/v1/stream?token=KEY	Real-time WebSocket stream
GET	/api/v1/feed?address=ADDR&token=KEY	RSS Atom feed (address optional, omits for global)

Skills endpoints

Method	Path	Description
GET	/api/v1/skills	List all skills
POST	/api/v1/skills	Create a skill
GET	/api/v1/skills/:id	Get a skill
PUT	/api/v1/skills/:id	Update a skill
DELETE	/api/v1/skills/:id	Delete a skill
POST	/api/v1/skills/:id/toggle	Enable/disable a skill
POST	/api/v1/skills/:id/test	Test-run a skill on a sample message
GET	/api/v1/skills/:id/runs	List recent skill runs (output, tokens, errors)

Management endpoints

Method	Path	Description
GET	/api/v1/sources	List IMAP sources
POST	/api/v1/sources	Add IMAP source
DELETE	/api/v1/sources/:id	Remove IMAP source
POST	/api/v1/sources/:id/poll	Trigger immediate poll of a source
GET	/api/v1/api-keys	List API keys
POST	/api/v1/api-keys	Create API key
DELETE	/api/v1/api-keys/:id	Delete API key
GET	/api/v1/ai/config	Get AI/LLM config
PUT	/api/v1/ai/config	Update AI/LLM config
GET	/api/v1/config	Get full config
PUT	/api/v1/config	Update full config (raw JSON edit)
POST	/api/v1/restart	Restart the app container
GET	/api/v1/stats	App statistics
POST	/api/v1/test/email	Send a test email
POST	/api/v1/test/llm	Test LLM connection
POST	/api/v1/test/ntfy	Test ntfy connection
GET	/api/v1/bots-doc	Bot integration guide (markdown)

Wait-for-email (the killer feature)

# Wait up to 60 seconds for an email to arrive at this address
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-app.example.com/api/v1/addresses/test@catch.com/wait?timeout=60&expected_from=github.com"

Returns the message as soon as it arrives, or 204 if timeout.

Authentication

• Web UI: site password (session cookie)
• API: API key via X-API-Key header
• WebSocket: ?token=API_KEY query param
• RSS: ?token=API_KEY query param

API keys are created in the UI (Settings → API Keys section) or via the API. The same key works for all auth methods — there are no separate tokens for WebSocket or RSS.

Skills

Skills are markdown instruction documents that tell an LLM how to process incoming email. A skill:

1. Matches incoming messages by trigger (always, address glob, domain, subject regex, extracted type, or fallback-only)
2. Sends the email content + your markdown prompt to the LLM (any OpenAI-compatible API)
3. Receives structured JSON output (summary, keep/discard, custom fields)
4. Delivers the result via configured routes (email, ntfy)
5. Optionally deletes the message (keep: false)

All matching skills run in priority order — they are not exclusive.

See docs/bots.md (also available in-app under the Bots page) for the full bot integration guide.

Trashmail use

Yes — mailCatch works perfectly as a disposable/trashmail service:

• Create a random address (or use the "Random" button in the UI)
• Give it to whatever service asks for an email
• Receive the email in the web UI — read it, extract verification codes, click links
• Set a TTL (in hours) so the address auto-expires
• Or delete/burn the address manually when done
• Expired or deleted addresses silently discard any new mail

No registration, no signup, no personal data exposed.

License

Apache License 2.0