Mail Relay Service

Builds MIME emails, bridges HTTP requests to SMTP delivery, and parses inbound messages using the standard library's advanced networking features.

Capabilities

Build and send MIME email

• With sender, recipients, subject, text body, and optional attachment path, builds a MIME message, sends it via authenticated TLS SMTP, and returns the server's acknowledgement string. @test
• When an attachment path is provided but the file is missing, the send attempt fails fast with a clear error before any network send is attempted. @test

HTTP webhook to SMTP bridge

• Exposes an HTTP endpoint at /send that accepts POST JSON payloads with email details, responds with HTTP 202 and a short JSON acknowledgement once the payload is queued for delivery, and triggers asynchronous send using the provided SMTP configuration. @test
• Non-POST requests to /send are rejected with HTTP 405. @test

Parse inbound EML

• Given raw RFC 5322 message bytes (including attachments), returns a parsed summary containing subject, sender, all recipients, extracted plain-text body, and attachment metadata (filename and size). @test

Graceful shutdown

• When shutdown is requested, the server stops accepting new HTTP requests, cancels pending deliveries, and closes network sockets cleanly. @test

Implementation

@generates

API

from dataclasses import dataclass
from typing import List, Optional, Dict, Any


@dataclass
class SMTPConfig:
    host: str
    port: int
    username: str
    password: str
    use_tls: bool
    timeout: float


@dataclass
class EmailPayload:
    sender: str
    to: List[str]
    cc: Optional[List[str]]
    subject: str
    text_body: str
    attachment_path: Optional[str] = None


@dataclass
class ParsedMessage:
    subject: str
    sender: str
    recipients: List[str]
    text_body: str
    attachments: List[Dict[str, Any]]


class MailRelay:
    def __init__(self, smtp: SMTPConfig, host: str = "127.0.0.1", port: int = 0):
        ...

    async def start(self) -> int:
        """Starts HTTP listener, returning the bound port."""

    async def stop(self) -> None:
        """Stops HTTP listener and pending deliveries."""

    async def deliver(self, payload: EmailPayload) -> str:
        """Sends immediately via SMTP, returning a server acknowledgement string."""

    def parse_eml(self, raw_message: bytes) -> ParsedMessage:
        """Parses raw message bytes into structured data."""

Dependencies { .dependencies }

Python standard library (advanced networking) { .dependency }

Provides HTTP serving primitives, email composition/parsing, secure SMTP clients, and event loop tools needed for asynchronous network handling.