---
id: TASK-74
title: Email forwarding via Mailcow aliases (username@rspace.online)
status: Done
assignee: []
created_date: '2026-03-01 05:55'
labels:
  - encryptid
  - email
  - infrastructure
dependencies: []
references:
  - src/encryptid/mailcow.ts
  - src/encryptid/server.ts
  - src/encryptid/db.ts
  - src/encryptid/schema.sql
  - docker-compose.encryptid.yml
priority: medium
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Users get username@rspace.online email addresses that forward to their personal email. Uses Mailcow API to create lightweight forwarding aliases — no full mailboxes needed. Users toggle it on in profile settings via API.

Pure alias approach: can be upgraded to hybrid (agent-processes-first) model later by swapping aliases for a catch-all.

## Implementation
- New `mailcow.ts` API client wrapping Mailcow REST API (create/delete/update/find aliases)
- Schema: `email_forward_enabled` + `email_forward_mailcow_id` columns on users table
- DB layer: `getEmailForwardStatus()` + `setEmailForward()` functions
- API endpoints: GET/POST `/api/account/email-forward` (status, enable, disable)
- Profile email change hook: auto-updates or disables alias when profile email changes
- Docker: encryptid container joins rmail-mailcow network for internal API access

## Infrastructure
- rspace.online already configured as Mailcow domain with MX/SPF/DKIM/DMARC
- Mailcow API key stored in /opt/encryptid/.env on server
- Internal API URL: http://nginx-mailcow:8080 (via Docker network)
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Mailcow API client creates/deletes/updates forwarding aliases
- [ ] #2 GET /api/account/email-forward returns status and availability
- [ ] #3 POST enable creates alias and stores mailcow ID in DB
- [ ] #4 POST disable deletes alias from Mailcow and clears DB
- [ ] #5 Profile email change auto-updates or disables active alias
- [ ] #6 Schema migration is idempotent (ALTER TABLE IF NOT EXISTS)
- [ ] #7 Graceful degradation when MAILCOW_API_KEY not set (available: false)
- [ ] #8 Docker compose includes rmail-mailcow network and env vars
<!-- AC:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Implemented email forwarding via Mailcow aliases. Created mailcow.ts API client (~112 lines), added 2 DB columns + 2 helper functions, 3 API endpoints (GET status, POST enable, POST disable), profile email change hook, and Docker networking. All infrastructure prerequisites were already in place (rspace.online domain, MX/SPF/DKIM/DMARC records). API key added to /opt/encryptid/.env on server. Merged dev→main and pushed.
<!-- SECTION:FINAL_SUMMARY:END -->