maily-server 0.4.0__tar.gz

maily_server-0.4.0/.biome.json

@@ -0,0 +1,32 @@
+{
+  "formatter": {
+    "enabled": false
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "style": {
+        "useConst": "warn",
+        "noNonNullAssertion": "off",
+        "useTemplate": "off"
+      },
+      "complexity": {
+        "useOptionalChain": "off"
+      },
+      "correctness": {
+        "noUnusedVariables": "warn",
+        "noUnusedFunctionParameters": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "off",
+        "useIterableCallbackReturn": "off"
+      }
+    }
+  },
+  "files": {
+    "includes": [
+      "src/maily/static/js/**"
+    ]
+  }
+}

maily_server-0.4.0/.dockerignore

@@ -0,0 +1,87 @@
+# ==============================================================================
+# Docker Ignore Rules for maily
+# ==============================================================================
+
+# Git & VCS
+.git/
+.gitignore
+.gitattributes
+.github/
+
+# Python cache & build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Secrets and environment configurations
+.env
+.env.*
+!.env.example
+mailtm.key
+
+# Local SQLite databases & data files
+data/
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+
+# Logs
+*.log
+logs/
+
+# Testing, typing & linting caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+tests/
+.playwright-mcp/
+
+# IDE, Editor & OS files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Documentation, scratch and tool caches
+docs/
+overview.png
+ADDING_PROVIDERS.md
+.codegraph/
+.omo/
+.ignore
+CACHEDIR.TAG
+run-continuation
+3.10/
+0.16.8/
+0.17.2/
+v/

maily_server-0.4.0/.env.example

@@ -0,0 +1,57 @@
+# ============ maily — environment example ============
+# Copy to .env and fill in your values.
+# Without .env the service runs with defaults (empty API key, sqlite in CWD).
+
+# --- General ---
+# HTTP server host/port. Inside a Docker container the host must be 0.0.0.0.
+MAILY_HOST=0.0.0.0
+MAILY_PORT=8477
+
+# API key. When set, all requests require the X-API-Key header.
+# Leave empty for unauthenticated access (local/trusted network).
+MAILY_API_KEY=
+# MAILY_API_KEY=sk-your-secret-key
+
+# Path to SQLite database (defaults to maily.db in current working directory).
+# In Docker, volume /data is already mounted via docker-compose.
+# MAILY_DATABASE_URL=sqlite+aiosqlite:///maily.db
+# MAILY_DATABASE_URL=sqlite+aiosqlite:////data/maily.db
+
+# Encryption key (Fernet). If empty, auto-generated and saved to maily.key.
+# MAILY_SECRET_KEY=
+
+# Proxy for outbound requests to email providers (optional).
+# MAILY_PROXY=http://user:pass@127.0.0.1:8080
+
+# Retention auto-cleanup interval in seconds.
+MAILY_RETENTION_INTERVAL_SECONDS=60
+
+# Database maintenance (VACUUM, REINDEX, ANALYZE, PRAGMA checkpoint/optimize):
+# Whether DB maintenance is enabled during retention runs.
+# MAILY_DB_MAINTENANCE_ENABLED=true
+# Minimum maintenance interval in minutes (run at most once per X minutes; skipped on more frequent retention runs).
+# MAILY_DB_MAINTENANCE_INTERVAL_MINUTES=60
+# SQLite busy timeout in milliseconds (app waits for DB locks to release without crashing).
+# MAILY_SQLITE_BUSY_TIMEOUT_MS=60000
+
+# --- Gmail OAuth (optional; alternative: configure creds via admin UI) ---
+# MAILY_GMAIL_CLIENT_ID=1234567890-abc.apps.googleusercontent.com
+# MAILY_GMAIL_CLIENT_SECRET=GOCSPX-your-secret
+# MAILY_GMAIL_REDIRECT_URI=http://127.0.0.1:8477/v1/gmail/oauth/callback
+
+# --- Dynamic X-CORS-Header for temp-mail.io provider ---
+# Origin from which the X-CORS-Header secret is parsed (service homepage).
+# MAILY_TEMPMAIL_IO_ORIGIN=https://temp-mail.io
+# Manual secret override (takes precedence over cache/fetch). Usually not needed.
+# MAILY_TEMPMAIL_IO_CORS_HEADER=
+# TTL for cached header values in DB, seconds.
+MAILY_PROVIDER_HEADERS_TTL_SECONDS=21600
+
+# --- temp.tf provider ---
+# Allow dot-aliases for Gmail addresses (user.name@gmail.com)
+# MAILY_TEMP_TF_GMAIL_DOT=true
+# Allow plus-aliases for Gmail addresses (user+tag@gmail.com)
+# MAILY_TEMP_TF_GMAIL_PLUS=true
+
+# --- docker-compose: port exposure ---
+# MAILY_PORT=8477  # same port published by compose (8477:8477)

maily_server-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug Report
+about: Create a report to help us improve maily
+title: "fix: "
+labels: ["bug"]
+assignees: []
+---
+
+## Describe the Bug
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+1. Start server with `...`
+2. Run client method `...`
+3. See error
+
+## Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+## Environment & Versions
+
+- OS: [e.g. Ubuntu 24.04, macOS Sonoma, Windows 11]
+- Python Version: [e.g. 3.13.2]
+- `maily` Version: [e.g. 0.3.0]
+- Mode: [e.g. Docker, standalone client, local python]
+
+## Additional Context
+
+Add any other context, logs, or screenshots here.

maily_server-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest an idea or enhancement for maily
+title: "feat: "
+labels: ["enhancement"]
+assignees: []
+---
+
+## Is your feature request related to a problem? Please describe.
+
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+## Describe the Solution You'd Like
+
+A clear and concise description of what you want to happen.
+
+## Describe Alternatives You've Considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Additional Context
+
+Add any other context, API design sketches, or screenshots about the feature request here.

maily_server-0.4.0/.github/ISSUE_TEMPLATE/provider_outage.md

@@ -0,0 +1,30 @@
+---
+name: Provider Outage Report
+about: Automated or manual alert for external mail provider degradation
+title: '[Provider Outage] <Provider Name> (<slug>) health checks failing'
+labels: ['bug', 'provider-outage', 'automated-health']
+assignees: ''
+---
+
+## 🚨 Provider Outage Alert
+
+### 📋 Outage Summary
+* **Provider:** `<Provider Name>` (`<provider.slug>`)
+* **Consecutive Failures:** 3+
+* **Detected At:** `YYYY-MM-DD HH:MM UTC`
+* **Trigger:** Scheduled Health Suite / PR Verification
+
+### ❌ Failure Diagnostic
+* **Failed Stage:** `list_targets` / `create_mailbox` / `list_messages` / `email_delivery`
+* **Error Message:** `<error message>`
+* **Mailbox Tested:** `<address>`
+
+### 🔍 Diagnostic Logs & Trace
+```
+<paste error logs or stack trace here>
+```
+
+### 🛠️ Recommended Actions
+1. Check if the upstream provider website is currently online or undergoing DDoS/maintenance.
+2. Verify if upstream HTML structure, CSRF tokens, or API signatures changed.
+3. Check if IP ranges from GitHub Actions / CI runners are being blocked.

maily_server-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Description
+
+<!-- Provide a brief description of the changes introduced by this pull request. -->
+
+## Type of Change
+
+- [ ] 🐛 Bug fix (non-breaking change fixing an issue)
+- [ ] ✨ New feature (non-breaking change adding functionality)
+- [ ] 💥 Breaking change (fix or feature causing existing functionality to change)
+- [ ] 📚 Documentation update
+- [ ] ⚡ Performance improvement
+- [ ] ♻️ Code refactoring
+- [ ] 👷 CI / Build changes
+- [ ] 🧪 Tests
+
+## Checklist
+
+- [ ] My commit messages and PR title follow [Conventional Commits](https://www.conventionalcommits.org/)
+- [ ] I have run `uv run pytest` and all tests pass
+- [ ] I have run `uv run ruff check .` and `uv run ruff format --check .`
+- [ ] I have run `uv run mypy src client scripts` without typing errors
+- [ ] If changing `src/maily/standalone_client.py`, I have run `uv run python scripts/build_client.py`
+- [ ] Documentation has been updated accordingly
+- [ ] No sensitive credentials, private keys, or tokens are committed

maily_server-0.4.0/.github/dependabot.yml

@@ -0,0 +1,47 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "ci(actions)"
+    groups:
+      github-actions:
+        patterns: ["*"]
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "deps"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "ruff*"
+          - "mypy*"
+          - "pytest*"
+          - "coverage*"
+          - "deptry*"
+          - "vulture*"
+          - "mutmut*"
+      fastapi-stack:
+        patterns:
+          - "fastapi*"
+          - "uvicorn*"
+          - "starlette*"
+          - "pydantic*"
+          - "sqlalchemy*"
+          - "alembic*"
+          - "aiosqlite*"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "docker"

maily_server-0.4.0/.github/labeler.yml

@@ -0,0 +1,39 @@
+area:core:
+  - changed-files:
+      - any-glob-to-any-file: ['src/maily/app/**', 'src/maily/settings.py', 'src/maily/crypto.py']
+
+area:db:
+  - changed-files:
+      - any-glob-to-any-file: ['src/maily/db/**', 'alembic/**']
+
+area:providers:
+  - changed-files:
+      - any-glob-to-any-file: ['src/maily/providers/**']
+
+area:frontend:
+  - changed-files:
+      - any-glob-to-any-file: ['src/maily/static/**']
+
+area:tests:
+  - changed-files:
+      - any-glob-to-any-file: ['tests/**']
+
+area:client:
+  - changed-files:
+      - any-glob-to-any-file: ['client/**', 'src/maily/standalone_client.py', 'scripts/build_client.py']
+
+area:docs:
+  - changed-files:
+      - any-glob-to-any-file: ['docs/**', '*.md', '.github/workflows/pages.yml']
+
+area:ci:
+  - changed-files:
+      - any-glob-to-any-file: ['.github/**', 'Dockerfile', 'docker-compose.yml', 'pyproject.toml']
+
+security:
+  - changed-files:
+      - any-glob-to-any-file: ['src/maily/crypto.py', '.github/workflows/*audit*.yml', '.github/workflows/*gitleaks*.yml', '.github/workflows/*trivy*.yml', '.github/workflows/*codeql*.yml']
+
+dependencies:
+  - changed-files:
+      - any-glob-to-any-file: ['uv.lock', 'pyproject.toml']

maily_server-0.4.0/.github/provider_health_state.json

@@ -0,0 +1,39 @@
+{
+  "providers": {
+    "anonymmail.net": {
+      "consecutive_failures": 0,
+      "issue_number": null,
+      "last_status": "operational"
+    },
+    "dispoemail.org": {
+      "consecutive_failures": 0,
+      "issue_number": null,
+      "last_status": "operational"
+    },
+    "mail.tm": {
+      "consecutive_failures": 0,
+      "issue_number": null,
+      "last_status": "operational"
+    },
+    "noopmail.org": {
+      "consecutive_failures": 1,
+      "issue_number": null,
+      "last_status": "degraded"
+    },
+    "temp-mail.io": {
+      "consecutive_failures": 0,
+      "issue_number": null,
+      "last_status": "operational"
+    },
+    "temp.tf": {
+      "consecutive_failures": 0,
+      "issue_number": null,
+      "last_status": "operational"
+    },
+    "tempmail.plus": {
+      "consecutive_failures": 0,
+      "issue_number": null,
+      "last_status": "operational"
+    }
+  }
+}

maily_server-0.4.0/.github/release-drafter.yml

@@ -0,0 +1,46 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+
+categories:
+  - title: '🚀 Features & Enhancements'
+    semver-increment: minor
+    when:
+      labels:
+        - 'feature'
+        - 'enhancement'
+        - 'area:core'
+        - 'area:providers'
+  - title: '🐛 Bug Fixes'
+    semver-increment: patch
+    when:
+      labels:
+        - 'bug'
+        - 'fix'
+  - title: '🔒 Security Updates'
+    semver-increment: patch
+    when:
+      labels:
+        - 'security'
+  - title: '🧹 Maintenance & Dependencies'
+    semver-increment: patch
+    when:
+      labels:
+        - 'dependencies'
+        - 'area:ci'
+        - 'chore'
+  - type: 'version-resolver'
+    semver-increment: 'major'
+    when:
+      labels:
+        - 'major'
+        - 'breaking-change'
+
+version-resolver:
+  default: patch
+
+template: |
+  ## What's Changed
+
+  $CHANGES
+
+  **Full Changelog**: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...$RESOLVED_TAG

maily_server-0.4.0/.github/workflows/benchmarks.yml

@@ -0,0 +1,89 @@
+name: Performance Benchmarks Tracking
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '0 2 * * *' # Daily at 02:00 UTC
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+permissions:
+  contents: write
+  deployments: write
+
+jobs:
+  benchmark:
+    name: API & Database Benchmarks
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.15"
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
+
+      - name: Run Pytest Benchmarks
+        run: |
+          uv run pytest tests/test_benchmarks.py -n 0 --benchmark-only --benchmark-json=output.json
+
+      - name: Render Benchmark Summary Table
+        if: always() && hashFiles('output.json') != ''
+        run: |
+          python3 -c "
+          import json, os
+          with open('output.json') as f:
+              data = json.load(f)
+          summary = os.environ.get('GITHUB_STEP_SUMMARY')
+          if summary and 'benchmarks' in data:
+              with open(summary, 'a', encoding='utf-8') as sf:
+                  sf.write('### ⚡ Benchmark Results\n\n')
+                  sf.write('| Benchmark | Group | Mean (ms) | Ops/sec | Rounds |\n')
+                  sf.write('| :--- | :--- | :---: | :---: | :---: |\n')
+                  for b in data['benchmarks']:
+                      name = b.get('name', 'unknown')
+                      group = b.get('group', 'default') or 'default'
+                      stats = b.get('stats', {})
+                      mean_ms = f\"{stats.get('mean', 0) * 1000:.3f}\"
+                      ops = f\"{stats.get('ops', 0):,.1f}\"
+                      rounds = stats.get('rounds', 0)
+                      sf.write(f'| `{name}` | {group} | {mean_ms} | {ops} | {rounds} |\n')
+          "
+
+      - name: Upload Benchmark JSON Artifact
+        uses: actions/upload-artifact@v7
+        if: always() && hashFiles('output.json') != ''
+        with:
+          name: benchmark-results
+          path: output.json
+          retention-days: 14
+
+      - name: Store benchmark results
+        uses: benchmark-action/github-action-benchmark@v1
+        if: always() && hashFiles('output.json') != ''
+        continue-on-error: true
+        with:
+          tool: 'pytest'
+          output-file-path: output.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: true
+          gh-pages-branch: 'gh-pages'
+          benchmark-data-dir-path: 'dev/bench'
+          summary-always: true
+          alert-threshold: '150%'
+          fail-on-alert: false
+          comment-on-alert: false