agentmail-clone-v1 0.1.0

package/.env.example

@@ -0,0 +1,20 @@
+NODE_ENV=development
+PORT=3000
+APP_BASE_URL=http://localhost:3000
+APP_SHARED_DOMAIN=emailagent.dev
+ADMIN_EMAIL=jagan.ganti@gmail.com
+SESSION_SECRET=replace-with-a-long-random-secret-at-least-32-chars
+API_KEY_HASH_SECRET=replace-with-another-long-random-secret-at-least-32-chars
+
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/agentmail
+
+MAILGUN_API_KEY=
+MAILGUN_REGION=us
+MAILGUN_WEBHOOK_SIGNING_KEY=
+MAILGUN_ACCOUNT_DOMAIN=
+MAIL_FROM_EMAIL=
+
+DODO_PAYMENTS_API_KEY=
+DODO_PAYMENTS_ENVIRONMENT=test_mode
+DODO_PAYMENTS_WEBHOOK_KEY=
+DODO_PAYMENTS_PRODUCT_ID_PAID=

package/.github/workflows/docs-deploy.yml

@@ -0,0 +1,37 @@
+name: Docs Validate and Deploy
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'openapi/**'
+      - 'scripts/validate-docs.js'
+      - '.github/workflows/docs-deploy.yml'
+      - 'package.json'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'openapi/**'
+      - 'scripts/validate-docs.js'
+      - '.github/workflows/docs-deploy.yml'
+      - 'package.json'
+
+jobs:
+  docs-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate docs structure
+        run: npm run docs:validate

package/.github/workflows/landing-preview.yml

@@ -0,0 +1,43 @@
+name: Landing Validate and Preview
+
+on:
+  pull_request:
+    paths:
+      - 'landing/**'
+      - 'scripts/validate-landing.js'
+      - 'package.json'
+      - '.github/workflows/landing-preview.yml'
+
+jobs:
+  landing-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate landing pages
+        run: npm run landing:validate
+
+  landing-preview:
+    if: ${{ secrets.NETLIFY_AUTH_TOKEN != '' && secrets.NETLIFY_SITE_ID != '' }}
+    needs: landing-validate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Deploy Netlify preview
+        uses: netlify/actions/cli@master
+        with:
+          args: deploy --dir=landing --alias pr-${{ github.event.pull_request.number }} --message "Landing preview for PR #${{ github.event.pull_request.number }}"
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

package/.github/workflows/openapi-lint.yml

@@ -0,0 +1,31 @@
+name: OpenAPI Lint
+
+on:
+  pull_request:
+    paths:
+      - 'openapi/**'
+      - 'package.json'
+  push:
+    branches:
+      - main
+    paths:
+      - 'openapi/**'
+      - 'package.json'
+
+jobs:
+  lint-openapi:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint OpenAPI
+        run: npm run lint:openapi

package/.github/workflows/sdk-generate-check.yml

@@ -0,0 +1,66 @@
+name: SDK Generate Check
+
+on:
+  pull_request:
+    paths:
+      - 'openapi/**'
+      - 'sdks/**'
+      - 'scripts/generate-sdk-*.sh'
+      - '.github/workflows/sdk-generate-check.yml'
+      - 'package.json'
+  push:
+    branches:
+      - main
+    paths:
+      - 'openapi/**'
+      - 'sdks/**'
+      - 'scripts/generate-sdk-*.sh'
+      - '.github/workflows/sdk-generate-check.yml'
+      - 'package.json'
+
+jobs:
+  sdk-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Generate SDKs
+        run: npm run generate:sdks
+
+      - name: Check generated output is committed
+        run: git diff --exit-code
+
+      - name: TypeScript SDK build smoke test
+        run: |
+          npm --prefix sdks/typescript install --no-fund --no-audit
+          npm --prefix sdks/typescript run build
+
+      - name: Python SDK build smoke test
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build sdks/python
+          python -m pip install -e sdks/python
+          python - <<'PY'
+          import emailagent_sdk
+          print('emailagent_sdk import ok')
+          PY

package/.github/workflows/sdk-release.yml

@@ -0,0 +1,62 @@
+name: SDK Release
+
+on:
+  push:
+    tags:
+      - 'sdk-ts-v*'
+      - 'sdk-py-v*'
+
+jobs:
+  publish-typescript:
+    if: startsWith(github.ref, 'refs/tags/sdk-ts-v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Set package version from tag
+        working-directory: sdks/typescript
+        run: |
+          VERSION="${GITHUB_REF_NAME#sdk-ts-v}"
+          npm version "$VERSION" --no-git-tag-version
+
+      - name: Install and build
+        run: |
+          npm --prefix sdks/typescript install --no-fund --no-audit
+          npm --prefix sdks/typescript run build
+
+      - name: Publish npm package
+        working-directory: sdks/typescript
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-python:
+    if: startsWith(github.ref, 'refs/tags/sdk-py-v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build Python package
+        run: |
+          python -m pip install --upgrade pip build
+          VERSION="${GITHUB_REF_NAME#sdk-py-v}"
+          sed -i "s/^version = .*/version = \"$VERSION\"/" sdks/python/pyproject.toml
+          python -m build sdks/python
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: sdks/python/dist

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.2.0 - Docs and SDK Foundation
+
+- Added Mintlify docs workspace under `docs/`.
+- Added API docs pages and deployment guidance for `docs.emailagent.dev`.
+- Added SDK scaffolding for TypeScript and Python in `sdks/`.
+- Added OpenAPI-driven SDK generation scripts.
+- Added GitHub Actions workflows for OpenAPI lint, SDK generation checks, SDK releases, and docs deployment.
+- Added release policy in `RELEASING.md`.

package/README.md

@@ -0,0 +1,208 @@
+# Agent Inbox SaaS (V1)
+
+Fastify + Postgres + HTMX app with:
+- Local signup/login (name + email + password)
+- Signup email verification, welcome email, and forgot/reset password email flow
+- Default organization creation on signup/login
+- Inboxes page (CRUD + compose + messages)
+- Domains page (CRUD + DNS records + verification)
+- API Keys page (create/list/revoke)
+- Metrics page (monthly usage + plan limits)
+- Billing page (free vs paid table + upgrade flow)
+- Admin page (restricted by admin email) for global metrics and plan-limit tuning
+- Mailgun adapter for sends, domain provisioning, and inbound/event webhooks
+- Dodo Payments checkout integration for free -> paid upgrade
+- API-key based external API for agent operations
+- Reliability primitives: idempotency keys, webhook dedupe, basic rate limiting, delivery status tracking
+
+## Stack
+- Node.js (Fastify)
+- PostgreSQL
+- EJS + HTMX
+- Mailgun (optional but integrated)
+
+## Plan enforcement
+- Free plan: `1` inbox, `0` custom domains, `1000` monthly outbound emails
+- Paid plan: `10` inboxes, `1` custom domain, `10000` monthly outbound emails
+
+Default org plan is `free` at signup.
+
+## Host mapping
+- Landing: `https://emailagent.dev`
+- App UI: `https://app.emailagent.dev`
+- API: `https://api.emailagent.dev`
+- Docs: `https://docs.emailagent.dev`
+
+Important: production Render env vars must use public production URLs. Do not use localhost values in production (`APP_BASE_URL` especially).
+
+## Quick start
+1. Install deps:
+   ```bash
+   npm install
+   ```
+2. Copy env file:
+   ```bash
+   cp .env.example .env
+   ```
+3. Configure `.env`:
+   - `DATABASE_URL`
+   - `APP_BASE_URL`
+   - `APP_SHARED_DOMAIN`
+   - `ADMIN_EMAIL`
+   - `SESSION_SECRET`
+   - `API_KEY_HASH_SECRET`
+   - Mailgun creds (optional for local mock behavior)
+   - Optional `MAIL_FROM_EMAIL` (defaults to `no-reply@MAILGUN_ACCOUNT_DOMAIN`)
+   - Dodo Payments creds (required for in-app upgrade flow)
+4. Run migration:
+   ```bash
+   npm run migrate
+   ```
+5. Start server:
+   ```bash
+   npm run dev
+   ```
+6. Open:
+   - UI: `http://localhost:3000`
+   - Health: `http://localhost:3000/healthz`
+
+## Run locally (app + landing + docs)
+Open separate terminals from `/Users/jaganganti/Documents/emailagent`.
+
+1. App (Fastify):
+   ```bash
+   npm run dev
+   ```
+   - URL: `http://localhost:3000`
+
+2. Landing site (static):
+   ```bash
+   npm run landing:dev
+   ```
+   - URL: `http://localhost:8080`
+
+3. Docs (Mintlify):
+   ```bash
+   cd docs
+   npx mintlify dev
+   ```
+   - URL: `http://localhost:3000` (or use `npx mintlify dev --port 3001` if 3000 is busy)
+
+## Docs and SDK workspace
+- Public landing site: `landing/`
+- Mintlify docs config and pages: `docs/`
+- OpenAPI source of truth: `openapi/openapi.yaml`
+- TypeScript SDK: `sdks/typescript/`
+- Python SDK: `sdks/python/`
+
+Validation and generation:
+
+```bash
+npm run lint:openapi
+npm run docs:validate
+npm run landing:validate
+npm run generate:sdks
+```
+
+## Landing deployment (Netlify)
+- Netlify publish directory: `landing`
+- Root domain: `emailagent.dev`
+- `www.emailagent.dev` should redirect to apex
+- Detailed setup: `landing/DEPLOYING.md`
+- Optional PR preview workflow requires GitHub secrets:
+  - `NETLIFY_AUTH_TOKEN`
+  - `NETLIFY_SITE_ID`
+
+## Mailgun endpoints used
+- `POST /v4/domains` (create custom domain)
+- `PUT /v4/domains/{name}/verify` (verify)
+- `DELETE /v4/domains/{name}` (delete)
+- `POST /v3/{domain}/messages` (send email)
+
+Webhooks in this app:
+- `POST /webhooks/mailgun/inbound`
+- `POST /webhooks/mailgun/events`
+- `POST /webhooks/dodo`
+
+## Shared-domain inbound route (manual)
+For shared-domain inboxes (for example `agent@emailagent.dev`), configure Mailgun Routes manually:
+
+- Expression: `match_recipient('.*@emailagent.dev')`
+- Action 1: `forward('https://app.emailagent.dev/webhooks/mailgun/inbound')`
+- Action 2: `stop()`
+
+Set `MAILGUN_WEBHOOK_SIGNING_KEY` in app env to validate webhook signatures.
+
+Expected inbound webhook responses:
+
+| Response | Meaning |
+| --- | --- |
+| `200 {"ok":true}` | Inbound accepted and stored |
+| `200 {"ok":true,"duplicate":true}` | Duplicate webhook ignored |
+| `202 {"ok":true,"ignored":true}` | Recipient does not match active inbox |
+| `401 {"error":"invalid signature"}` | Signing key mismatch |
+
+Inbound smoke test:
+1. Create inbox on shared domain.
+2. Send external email to that inbox.
+3. Confirm message appears in dashboard.
+4. Confirm message via `GET /api/v1/emails?inboxId=<inbox_uuid>`.
+
+## Custom Domain Onboarding
+- Paid users can add custom domains from `/app/domains`.
+- App creates the domain in Mailgun, fetches DNS records, and stores pending/active status.
+- App auto-provisions an inbound Mailgun route per custom domain that forwards to:
+  - `<APP_BASE_URL>/webhooks/mailgun/inbound`
+- Verify DNS refreshes records and status, and ensures inbound route is present.
+- Deleting a domain removes both Mailgun route and Mailgun domain (best effort), then soft-deletes locally.
+
+## Dodo Payments env vars
+- `DODO_PAYMENTS_API_KEY`
+- `DODO_PAYMENTS_ENVIRONMENT` (`test_mode` or `live_mode`)
+- `DODO_PAYMENTS_WEBHOOK_KEY`
+- `DODO_PAYMENTS_PRODUCT_ID_PAID` (the $10/mo paid plan product ID in Dodo)
+
+## API key auth
+Use `Authorization: Bearer <api_key>`.
+
+For mutating API calls, provide an optional `Idempotency-Key` header.
+If the same key is retried with the same payload, the cached response is returned.
+
+Example scopes:
+- `inboxes:read`, `inboxes:write`
+- `emails:read`, `emails:write`, `emails:send`
+- `domains:read`, `domains:write`
+- `keys:read`, `keys:write`
+- `metrics:read`
+- `*` (full access)
+
+## External API (V1)
+
+Canonical API contract: `openapi/openapi.yaml`
+
+- `GET /api/v1/inboxes`
+- `POST /api/v1/inboxes`
+- `PATCH /api/v1/inboxes/:id`
+- `DELETE /api/v1/inboxes/:id`
+- `POST /api/v1/emails/send`
+- `GET /api/v1/emails`
+- `PATCH /api/v1/emails/:id/read`
+- `DELETE /api/v1/emails/:id`
+- `GET /api/v1/domains`
+- `POST /api/v1/domains`
+- `POST /api/v1/domains/:id/verify`
+- `DELETE /api/v1/domains/:id`
+- `GET /api/v1/api-keys`
+- `POST /api/v1/api-keys`
+- `POST /api/v1/api-keys/:id/revoke`
+- `POST /api/v1/api-keys/:id/rotate`
+- `GET /api/v1/metrics`
+
+## Notes
+- This is V1 and intentionally excludes pods/threading.
+- Domain creation is blocked on free plan.
+- All dashboard pages are accessible to authenticated users; feature limits are enforced on actions.
+- To upgrade an org to paid for testing:
+  ```sql
+  UPDATE organizations SET plan = 'paid' WHERE id = '<org_id>';
+  ```

package/RELEASING.md

@@ -0,0 +1,43 @@
+# Releasing
+
+## API contract policy
+
+- `openapi/openapi.yaml` is the source of truth.
+- V1 policy is additive-only.
+- Breaking changes require a new major API version.
+
+## SDK versioning
+
+- SDKs use semantic versioning.
+- Patch: docs, bug fixes, non-breaking generation updates.
+- Minor: additive endpoint/schema changes.
+- Major: breaking SDK API changes.
+
+## Tag conventions
+
+- TypeScript SDK release tag: `sdk-ts-vX.Y.Z`
+- Python SDK release tag: `sdk-py-vX.Y.Z`
+
+## Required secrets
+
+GitHub Actions secrets:
+
+- `NPM_TOKEN` for npm publish
+- `PYPI_API_TOKEN` for PyPI publish
+- `MINTLIFY_DEPLOY_HOOK_URL` for docs deploy hook (optional but recommended)
+
+## Release checklist
+
+1. `npm run lint:openapi`
+2. `npm run docs:validate`
+3. `PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH" npm run generate:sdks`
+4. `npm run check:sdk:drift`
+5. OpenAPI changes reviewed and accepted
+6. SDK generation check passes in CI
+7. Create release tags and push:
+   - `git tag sdk-ts-v0.1.0`
+   - `git tag sdk-py-v0.1.0`
+   - `git push origin sdk-ts-v0.1.0 sdk-py-v0.1.0`
+8. Verify package availability:
+   - npm: `npm view emailagent-sdk version`
+   - PyPI: `https://pypi.org/project/emailagent-sdk/`

package/docs/api-reference/api-keys.mdx

@@ -0,0 +1,11 @@
+---
+title: API Keys API
+description: Create, rotate, revoke, and list API keys.
+---
+
+Endpoints:
+
+- `GET /api/v1/api-keys`
+- `POST /api/v1/api-keys`
+- `POST /api/v1/api-keys/{id}/rotate`
+- `POST /api/v1/api-keys/{id}/revoke`

package/docs/api-reference/domains.mdx

@@ -0,0 +1,13 @@
+---
+title: Domains API
+description: Manage custom domains and DNS verification.
+---
+
+Endpoints:
+
+- `GET /api/v1/domains`
+- `POST /api/v1/domains`
+- `POST /api/v1/domains/{id}/verify`
+- `DELETE /api/v1/domains/{id}`
+
+Custom domains are plan-gated.

package/docs/api-reference/emails.mdx

@@ -0,0 +1,26 @@
+---
+title: Emails API
+description: Send outbound email and consume inbound/outbound records.
+---
+
+Endpoints:
+
+- `POST /api/v1/emails/send`
+- `GET /api/v1/emails`
+- `PATCH /api/v1/emails/{id}/read`
+- `DELETE /api/v1/emails/{id}`
+
+Use `Idempotency-Key` for retries and to avoid duplicate sends.
+
+Required scopes:
+
+- `emails:send` for `POST /api/v1/emails/send`
+- `emails:read` for `GET /api/v1/emails`
+- `emails:write` for `PATCH /api/v1/emails/{id}/read` and `DELETE /api/v1/emails/{id}`
+
+Example:
+
+```bash
+curl -X GET "https://api.emailagent.dev/api/v1/emails?inboxId=<inbox_uuid>" \
+  -H "Authorization: Bearer <api_key>"
+```

package/docs/api-reference/inboxes.mdx

@@ -0,0 +1,13 @@
+---
+title: Inboxes API
+description: Create, list, update, and delete inboxes.
+---
+
+Endpoints:
+
+- `GET /api/v1/inboxes`
+- `POST /api/v1/inboxes`
+- `PATCH /api/v1/inboxes/{id}`
+- `DELETE /api/v1/inboxes/{id}`
+
+See full schema in `openapi/openapi.yaml`.

package/docs/api-reference/metrics.mdx

@@ -0,0 +1,10 @@
+---
+title: Metrics API
+description: View current usage and plan limits.
+---
+
+Endpoint:
+
+- `GET /api/v1/metrics`
+
+Returns sent/inbound counts and current plan limits.

package/docs/authentication.mdx

@@ -0,0 +1,25 @@
+---
+title: Authentication
+description: API key authentication and scopes.
+---
+
+All API requests use bearer auth:
+
+```http
+Authorization: Bearer <api_key>
+```
+
+## Scope model
+
+Common scopes:
+
+- `inboxes:read`, `inboxes:write`
+- `emails:read`, `emails:write`, `emails:send`
+- `domains:read`, `domains:write`
+- `keys:read`, `keys:write`
+- `metrics:read`
+- `*` for full access
+
+If scope is missing, API returns `403`.
+
+If API key is missing or invalid, API returns `401`.

package/docs/docs.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "name": "EmailAgent Docs",
+  "theme": "mint",
+  "favicon": "/favicon.svg",
+  "colors": {
+    "primary": "#0c6f5c",
+    "light": "#0f8270",
+    "dark": "#0a5a4b"
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "Getting Started",
+        "pages": [
+          "index",
+          "quickstart",
+          "authentication",
+          "idempotency",
+          "errors"
+        ]
+      },
+      {
+        "group": "API Reference",
+        "pages": [
+          "api-reference/inboxes",
+          "api-reference/emails",
+          "api-reference/domains",
+          "api-reference/api-keys",
+          "api-reference/metrics"
+        ]
+      }
+    ]
+  }
+}