Maltonoloco/mail service

[maltonoloco]

Feature

Description

Adds a provider-neutral mail service for the OpenTaberna admin backend.

The service uses IMAP to access incoming mail and SMTP to send messages. It can connect to hosted or self-hosted mail servers and provides the API foundation required for a future webmail client in the admin frontend.

The implementation includes:

• listing mailbox folders
• listing and searching messages
• retrieving complete messages
• downloading attachments
• sending plain-text and HTML messages
• moving messages between folders
• updating message flags
• deleting messages
• checking mailbox configuration status
• local SMTP/IMAP testing through GreenMail

Mailbox operations are separated into router, service, adapter, and model layers. Blocking IMAP and SMTP operations run outside the FastAPI event loop.

Motivation

OpenTaberna needs centralized mailbox functionality that can later be accessed through the admin frontend.

Using an adapter interface keeps the backend independent from a specific mail provider. The current IMAP/SMTP implementation supports standard hosted and self-hosted mail servers, while additional adapters such as Microsoft Graph can be added later.

GreenMail provides an isolated local development environment without requiring a registered domain, external mail server, or DNS configuration.

API Changes

• New endpoints added
• Existing endpoints modified
• Breaking changes

New admin-only endpoints under /v1/admin/mail:

• GET /status — return mailbox configuration status
• GET /folders — list available folders
• GET /folders/{folder}/messages — list and search messages
• GET /folders/{folder}/messages/{uid} — retrieve a message
• GET /folders/{folder}/messages/{uid}/attachments/{part_id} — download an attachment
• POST /messages — send a message
• POST /folders/{folder}/messages/{uid}/move — move a message
• PATCH /folders/{folder}/messages/{uid}/flags — update message flags
• DELETE /folders/{folder}/messages/{uid} — delete a message

All endpoints require an authenticated Keycloak administrator token issued to the configured admin frontend client.

Database Changes

• New tables/columns added
• Migrations required
• No database changes

Messages remain on the configured mail server and are accessed through IMAP. The OpenTaberna database does not duplicate mailbox contents.

Documentation

• API documentation updated (docs/)
• README updated if necessary
• Code comments added

The new endpoints are included in the generated OpenAPI and Swagger documentation.

The required mailbox environment variables are documented in .env.example.

Testing

• Unit tests added/updated
• Integration tests added/updated
• All relevant tests passing

Validation performed:

• mail schema validation tests
• router-to-service delegation test
• service-to-adapter flag conversion test
• outgoing message Date header test
• Ruff formatting check
• Ruff linting across src/ and tests/
• Python compilation check
• OpenAPI schema generation check
• manual SMTP-to-IMAP end-to-end test through GreenMail

Manual development flow verified:

OpenTaberna API → SMTP → GreenMail → IMAP → OpenTaberna API

Checklist

• Code follows project style guidelines
• Environment variables documented in .env.example if needed