MailGap Proxy Email Service Specification

Status: Canonical (Final) Last Updated: 2026-02-06 Owner: Engineering

Purpose

This specification defines the MailGap Proxy Email Service.

MailGap provides users with proxy email addresses that:

  • Protect their real email identity
  • Prevent direct exposure to third parties
  • Enforce strict safety, abuse, and compliance controls

MailGap operates as a private, in-application inbox. Emails are received and managed inside MailGap and are not forwarded to a user’s personal email address.

This document defines what is built. System-wide invariants are defined in contracts and MUST NOT be redefined here.

Scope

This specification covers:

  • Proxy email address creation and lifecycle
  • Inbound email handling into the MailGap inbox
  • Outbound reply-only behavior from MailGap
  • Credit and rate-limit enforcement
  • Abuse prevention and suppression
  • Storage of messages and attachments
  • User-facing MailGap UI behavior (high-level)

Out of scope:

  • Email forwarding to real inboxes
  • SMTP or IMAP client access
  • Bulk or campaign email
  • HTML email rendering (plain text only)
  • Attachments in outbound replies

Product Principles

MailGap is built on the following principles:

  1. Air-gapped inbox — messages stay inside MailGap
  2. Reply-only sending — no new outbound composition
  3. Shared reputation protection — infrastructure safety over convenience
  4. Plain text first — privacy and safety by default
  5. Explicit user intent — no silent automation

Terminology

  • Alias: A proxy email address issued to a user
  • Inbound message: An email delivered into the MailGap inbox
  • Outbound reply: A reply sent from MailGap to the original sender
  • Credit: Unit used to limit usage
  • Suppression: Forced block due to abuse, bounce, or complaint

Alias Model

Alias Creation

  • Aliases are generated by the system
  • Alias format is opaque and non-guessable
  • Optional user-provided label may be prepended
  • Alias count is limited by subscription tier

Aliases MUST be owned by a single user.

Alias States

State Receives Mail Can Reply Description
active Yes Yes Normal operation
paused No No Temporarily disabled by user
disabled No No Permanently disabled

State changes MUST be server-side enforced.

Inbound Email Handling

Receipt

  • Inbound email is received via the configured email provider
  • Messages are delivered into the MailGap inbox only
  • No forwarding to external inboxes occurs

Processing

On receipt:

  1. Validate alias exists and is active
  2. Enforce inbound rate limits
  3. Convert content to plain text
  4. Strip trackers and active content
  5. Store message metadata and body
  6. Store attachments in AWS S3
  7. Consume inbound credits

Daily caps described in pricing apply to inbound messages received by MailGap aliases, not forwarding activity.

Inbound handling MUST comply with:

  • docs/contracts/rls-standard.new.md
  • docs/contracts/data-retention.new.md
  • docs/contracts/rate-limits-and-abuse.new.md

Outbound Reply Behavior

Reply-Only Enforcement

Outbound email is permitted ONLY as a reply to an inbound message.

Rules:

  • Exactly one recipient (original sender)
  • No CC or BCC
  • No forwarding
  • No new message composition
  • Subject is prefixed with “Re:”

Violations MUST be rejected server-side.

Credit Consumption

  • Inbound message: 1 credit
  • Outbound reply: weighted cost per abuse contract

Credits:

  • Reset daily
  • Cannot go negative
  • Are not transferable

Rate Limits and Abuse Controls

MailGap is subject to strict abuse controls:

  • Per-alias inbound limits
  • Per-recipient outbound cooldowns
  • Duplicate reply detection
  • Suppression lists (bounces, complaints)
  • Hard daily email caps

Abuse enforcement MUST follow:

  • docs/contracts/rate-limits-and-abuse.new.md

Suppression and Safety

Suppression occurs when:

  • A recipient bounces
  • A spam complaint is received
  • Abuse thresholds are crossed
  • Provider reputation risk is detected

Suppressed addresses:

  • Cannot be replied to
  • Override user intent
  • Are not user-removable

Attachments (Inbound Only)

Inbound attachments:

  • Are stored in AWS S3
  • Are size-limited
  • Are type-restricted
  • Are associated with a Postgres metadata record

Outbound replies MUST NOT include attachments.

Data Storage

Postgres

Stored data includes:

  • Alias records
  • Message metadata
  • Credit usage
  • Suppression flags

All tables MUST:

  • Use UUID primary keys
  • Enforce RLS
  • Track ownership explicitly

AWS S3

Used for:

  • Email attachments
  • Compliance-regulated documents (if applicable)

Rules:

  • Private buckets only
  • Signed URL access
  • Lifecycle aligned with retention contract

Authorization and Access Control

  • Users may only access their own aliases and messages
  • Admin access is restricted and logged
  • All access enforced via RLS and server checks

Authorization MUST comply with:

  • docs/contracts/authz-and-roles.new.md
  • docs/contracts/rls-standard.new.md

User Interface (High-Level)

MailGap UI provides:

  • Alias list
  • Inbox per alias
  • Message detail view
  • Reply composer (plain text)
  • Blocked / suppressed state messaging
  • Credit usage indicators

UI gating is advisory only.

Error Handling

Errors MUST:

  • Be explicit and user-safe
  • Not reveal abuse detection logic
  • Be logged for observability

Compliance Considerations

MailGap MUST support:

  • Data retention enforcement
  • Audit logging
  • Access controls
  • Abuse evidence retention

Compliance rules are defined in:

  • docs/contracts/data-retention.new.md

Out of Scope (Explicit)

The following are explicitly excluded:

  • Email forwarding to personal inboxes
  • SMTP or IMAP access
  • Bulk email
  • Marketing email
  • HTML rendering
  • Message search (v1)

Acceptance Criteria

  • Users can create and manage aliases
  • Inbound email is received into MailGap
  • Replies are possible only to received messages
  • Abuse limits are enforced
  • Suppression overrides user intent
  • RLS prevents cross-user access

References

  • docs/governance/doc-authority.new.md
  • docs/contracts/authz-and-roles.new.md
  • docs/contracts/data-retention.new.md
  • docs/contracts/rate-limits-and-abuse.new.md
  • docs/contracts/rls-standard.new.md
  • docs/architecture/system-overview.new.md

End of Document