Magpie

Why the name? A magpie is a bird famously known for collecting shiny things and bringing them back to its nest — which felt like an oddly perfect metaphor for an app that gathers emails from everywhere and brings them home.

Magpie is a lightweight, simplified email forwarding utility. It monitors multiple IMAP email accounts (Input Sources) and forwards all incoming messages to a single designated IMAP account (Output). It also implements a unique bidirectional deletion synchronization.

Features

• Multiple Input Sources: Monitor multiple IMAP accounts simultaneously.
• Single Output: Centralize all emails in one destination.
• Bidirectional Deletion Sync: Deleting a forwarded message in the Output account (by moving it to Trash) automatically deletes the original message in the Input Source.
• Simplified Design: Built with .NET 10 Minimal API for high performance and low overhead.
• Flat-file Storage: No database required; uses simple pipe-separated files for data persistence.
• Secure: IMAP passwords are encrypted using ASP.NET Core Data Protection.
• Web UI: Sleek, modern web interface for managing sources and monitoring status.
• Background Processing: Robust background loop handles polling and synchronization.

Privacy and Transparency

Magpie bends over backwards to make all code related to message handling transparent and auditable. We make no changes to the email payload — what goes in is what comes out.

If you inspect the DKIM-Signature header on both the source and destination messages, you should see the same bh (body hash) value, which is nerd-speak for “we didn’t touch it.”

That said, this software is provided as-is. Please don’t use it for anything that would get you fired, arrested, haunted, cursed, subpoenaed, or otherwise featured in a true-crime podcast.

System Architecture (Structural Information)

Magpie is designed for simplicity and reliability. Here is the structural breakdown to help understand the system:

1. Entry Point (Program.cs): An ASP.NET Core 10 Minimal API that hosts the Web UI, provides RESTful endpoints for configuration, and bootstraps the background service.

2. Background Service (MonitorLoop.cs): A BackgroundService that runs periodically (default every 15 minutes). It orchestrates the email polling and synchronization logic.

3. IMAP Provider (ImapProvider.cs): Wraps MailKit to provide high-level IMAP operations. It handles connection, authentication, fetching, and copying.

4. Storage Service (StorageService.cs): Manages data persistence using flat files (sources.dat and status.dat) in the /data directory. It uses IDataProtectionProvider to encrypt sensitive credentials.

5. Deletion Sync Mechanism:

   • When a message is forwarded from Input to Output, Magpie appends the Input source's email address as a custom IMAP keyword/flag to the message in the Output inbox.
   • During each loop, Magpie inspects the Trash folder of the Output account for messages with these keywords.
   • If a match is found, Magpie deletes the corresponding original message from the Input account, keeping both accounts in sync.

Getting Started

Prerequisites

• .NET 10 SDK

Building and Running

1. Clone the repository:

   git clone https://github.com/bigtech/magpie.git
   cd magpie

2. Build and Run:

   dotnet run --project Magpie

The application will be available at http://localhost:19000.

Running with Docker Compose

The application is available as a pre-built Docker image. You can run it using:

docker-compose up -d

The application stores its data in a named volume magpie_data, mapping to /data inside the container.

API

The application exposes a RESTful API for managing email sources and controlling the monitoring service. You can access the Swagger UI for the API at http://localhost:19000/swagger.

Key Endpoints

• GET /api/status: Retrieves email forwarding statistics for the last 7 days.
• GET /api/sources: Retrieves and manages all configured email sources.
• POST /api/sources/test: Tests the IMAP connection for a source before saving.
• GET /api/start / GET /api/stop: Controls the background monitoring loop.

Configuration

Magpie uses appsettings.json for configuration.

{
  "DataPath": "/data",
  "Monitor": {
    "SleepMinutes": 15
  }
}

• DataPath: Directory where the application will store its .dat files and Data Protection keys.
• Monitor:SleepMinutes: The interval in minutes between polling cycles.

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

License

This project is licensed under the MIT License. See the LICENSE file for more information.