agentmail-clone-v1 0.1.0

package/docs/errors.mdx

@@ -0,0 +1,34 @@
+---
+title: Errors
+description: Error format and status code guidance.
+---
+
+Error response shape:
+
+```json
+{
+  "error": "message"
+}
+```
+
+Common status codes:
+
+- `400` invalid request
+- `401` missing/invalid bearer token
+- `403` missing scope
+- `404` resource not found
+- `409` idempotency conflict
+- `422` plan/validation limits
+- `429` rate limited
+- `500` provider/internal failure
+
+Use idempotency keys and exponential backoff for retryable failures.
+
+## Inbound webhook statuses
+
+When Mailgun forwards inbound mail to `/webhooks/mailgun/inbound`:
+
+- `200` with `{"ok": true}`: inbound accepted and saved.
+- `200` with `{"ok": true, "duplicate": true}`: duplicate delivery ignored.
+- `202` with `{"ok": true, "ignored": true}`: recipient inbox not found.
+- `401`: signature verification failed (`MAILGUN_WEBHOOK_SIGNING_KEY` mismatch).

package/docs/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <rect width="64" height="64" rx="14" fill="#0c6f5c"/>
+  <path d="M16 22h32v20H16V22zm2 2v16h28V24H18z" fill="#ffffff"/>
+  <path d="M18 24l14 10 14-10" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/docs/idempotency.mdx

@@ -0,0 +1,18 @@
+---
+title: Idempotency
+description: Safe retries for mutating operations.
+---
+
+For mutating endpoints (`POST`, `PATCH`, `DELETE`), send:
+
+```http
+Idempotency-Key: <unique_operation_key>
+```
+
+Behavior:
+
+- Same key + same payload: original response is replayed.
+- Same key + different payload: `409` conflict.
+- In-progress duplicate: `409` conflict.
+
+Use deterministic keys from your agent action IDs for safe retries.

package/docs/index.mdx

@@ -0,0 +1,24 @@
+---
+title: EmailAgent API
+description: Email operations infrastructure for AI agents.
+---
+
+EmailAgent gives agents a simple API to:
+
+- Create and manage inboxes
+- Send outbound emails
+- Onboard and verify custom domains
+- Manage API keys and scopes
+- Track usage metrics
+
+The canonical API contract is generated from:
+
+- `openapi/openapi.yaml`
+
+Base domains:
+
+- App UI: `https://app.emailagent.dev`
+- API: `https://api.emailagent.dev`
+- Docs: `https://docs.emailagent.dev`
+
+Start with [Quickstart](./quickstart).

package/docs/quickstart.mdx

@@ -0,0 +1,134 @@
+---
+title: Quickstart
+description: Create an API key, send email, and consume inbound email records.
+---
+
+## 0. Install SDKs (optional)
+
+```bash
+npm install emailagent-sdk@0.1.0
+pip install emailagent-sdk==0.1.0
+```
+
+## 1. Authenticate
+
+Use a bearer API key from the dashboard.
+
+```bash
+curl -X GET "https://api.emailagent.dev/api/v1/inboxes" \
+  -H "Authorization: Bearer <api_key>"
+```
+
+## 2. Create inbox
+
+```bash
+curl -X POST "https://api.emailagent.dev/api/v1/inboxes" \
+  -H "Authorization: Bearer <api_key>" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: create-inbox-agent-1" \
+  -d '{
+    "localPart": "agent-1",
+    "displayName": "Agent One"
+  }'
+```
+
+## 3. Send email
+
+```bash
+curl -X POST "https://api.emailagent.dev/api/v1/emails/send" \
+  -H "Authorization: Bearer <api_key>" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: send-welcome-001" \
+  -d '{
+    "inboxId": "<inbox_uuid>",
+    "to": "alice@example.com",
+    "subject": "Hello",
+    "text": "Welcome from your AI agent"
+  }'
+```
+
+## 4. List and mark inbound email
+
+```bash
+curl -X GET "https://api.emailagent.dev/api/v1/emails?inboxId=<inbox_uuid>" \
+  -H "Authorization: Bearer <api_key>"
+```
+
+```bash
+curl -X PATCH "https://api.emailagent.dev/api/v1/emails/<email_uuid>/read" \
+  -H "Authorization: Bearer <api_key>" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: mark-read-001" \
+  -d '{"isRead": true}'
+```
+
+## 5. SDK examples
+
+```ts
+import { EmailAgentClient } from 'emailagent-sdk';
+
+const client = new EmailAgentClient({
+  apiKey: process.env.EMAILAGENT_API_KEY!,
+  baseUrl: 'https://api.emailagent.dev'
+});
+
+const inboxes = await client.listInboxes();
+const inboxId = inboxes.data[0].id;
+const emails = await client.listEmails({ inboxId });
+if (emails.data.length) {
+  await client.updateEmailRead(emails.data[0].id, true, { idempotencyKey: 'mark-read-001' });
+}
+```
+
+```python
+from emailagent_sdk import EmailAgentClient
+
+client = EmailAgentClient(api_key="<api_key>", base_url="https://api.emailagent.dev")
+inboxes = client.list_inboxes()
+inbox_id = inboxes["data"][0]["id"]
+emails = client.list_emails(inbox_id=inbox_id)
+if emails["data"]:
+    client.update_email_read(
+        email_id=emails["data"][0]["id"],
+        is_read=True,
+        idempotency_key="mark-read-001",
+    )
+```
+
+## 6. Shared-domain inbound route (manual setup)
+
+For shared-domain inboxes (for example `agent@emailagent.dev`), configure this in Mailgun Routes:
+
+- Expression: `match_recipient('.*@emailagent.dev')`
+- Action 1: `forward('https://app.emailagent.dev/webhooks/mailgun/inbound')`
+- Action 2: `stop()`
+
+Also set `MAILGUN_WEBHOOK_SIGNING_KEY` in app environment to enforce webhook signature validation.
+
+Expected successful webhook response:
+
+```json
+{"ok": true}
+```
+
+## 7. Inbound troubleshooting
+
+| Webhook response | Meaning | Action |
+| --- | --- | --- |
+| `401` | Invalid signature | Verify `MAILGUN_WEBHOOK_SIGNING_KEY` matches Mailgun webhook signing key |
+| `202` with `ignored: true` | Recipient does not map to active inbox | Create/check inbox local part and domain in app |
+| `200` with `duplicate: true` | Duplicate event received | No action needed; dedupe is working |
+
+## 8. Inbound smoke test
+
+1. Create inbox `agent@emailagent.dev` in app.
+2. Send email from external mailbox to that inbox.
+3. Confirm message appears in dashboard inbox view.
+4. Confirm same message appears via `GET /api/v1/emails?inboxId=<inbox_uuid>`.
+
+## 9. Check metrics
+
+```bash
+curl -X GET "https://api.emailagent.dev/api/v1/metrics" \
+  -H "Authorization: Bearer <api_key>"
+```

package/landing/DEPLOYING.md

@@ -0,0 +1,33 @@
+# Landing Deployment (Netlify)
+
+This project hosts the public landing page on the root domain.
+
+## Host mapping
+- `emailagent.dev` -> Netlify landing site
+- `www.emailagent.dev` -> redirect to `emailagent.dev`
+- `app.emailagent.dev` -> Render app
+- `api.emailagent.dev` -> Render API
+- `docs.emailagent.dev` -> Docs host
+
+## Netlify setup
+1. Connect this GitHub repo to Netlify.
+2. Build settings:
+   - Build command: (leave empty)
+   - Publish directory: `landing`
+3. Add custom domain `emailagent.dev`.
+4. Add `www.emailagent.dev` and configure redirect to apex.
+5. In DNS provider, point apex and `www` records to Netlify targets.
+
+## Optional PR previews from GitHub Actions
+Set these GitHub repository secrets:
+- `NETLIFY_AUTH_TOKEN`
+- `NETLIFY_SITE_ID`
+
+When configured, pull requests touching `landing/**` trigger preview deploys.
+
+## Analytics setup
+Edit `landing/index.html` and set values in `window.__landingAnalytics`:
+- `plausibleDomain` for Plausible
+- `ga4MeasurementId` for Google Analytics 4
+
+`landing/main.js` tracks CTA events (`cta_click`) for both providers when available.

package/landing/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <rect width="64" height="64" rx="14" fill="#0e7c66"/>
+  <path d="M14 22h36v20H14V22zm2 2v16h32V24H16z" fill="#fff"/>
+  <path d="M16 24l16 11 16-11" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/landing/index.html

@@ -0,0 +1,129 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>EmailAgent | Email Infrastructure for AI Agents</title>
+    <meta name="description" content="Provision inboxes, custom domains, API keys, and usage controls for AI agents with a simple API." />
+    <link rel="canonical" href="https://emailagent.dev" />
+    <meta property="og:title" content="EmailAgent" />
+    <meta property="og:description" content="Email infrastructure for AI agents." />
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content="https://emailagent.dev" />
+    <meta name="twitter:card" content="summary_large_image" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Sora:wght@500;600;700&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="./styles.css" />
+    <script>
+      window.__landingAnalytics = {
+        plausibleDomain: "",
+        ga4MeasurementId: ""
+      };
+    </script>
+    <script defer src="./main.js"></script>
+  </head>
+  <body>
+    <div class="noise"></div>
+    <header class="topbar">
+      <a href="/" class="brand">EmailAgent</a>
+      <nav class="topnav">
+        <a href="#pricing">Pricing</a>
+        <a href="https://docs.emailagent.dev" data-cta="docs-nav">Docs</a>
+        <a class="button ghost" href="https://app.emailagent.dev/" data-cta="login-nav">Log in</a>
+      </nav>
+    </header>
+
+    <main>
+      <section class="hero">
+        <p class="eyebrow">Built for API-first teams</p>
+        <h1>Email infrastructure for AI agents</h1>
+        <p class="lead">
+          Create agent inboxes, send and receive emails, manage custom domains, and issue scoped API keys.
+          No mailbox UI complexity. Just reliable primitives your agents can call.
+        </p>
+        <div class="cta-row">
+          <a class="button primary" href="https://app.emailagent.dev/" data-cta="start-free-hero">Start for free</a>
+          <a class="button secondary" href="https://docs.emailagent.dev" data-cta="docs-hero">Read API docs</a>
+        </div>
+        <p class="status-note">Built for agent workflows, not human mailbox clients.</p>
+      </section>
+
+      <section class="features" aria-label="Core product features">
+        <article>
+          <h2>Inbox provisioning</h2>
+          <p>Programmatically create and manage inbox identities for each agent persona.</p>
+        </article>
+        <article>
+          <h2>Custom domains</h2>
+          <p>Onboard and verify domains with DNS mapping and Mailgun-backed deliverability.</p>
+        </article>
+        <article>
+          <h2>API keys + scopes</h2>
+          <p>Issue scoped keys for tools and agents with explicit permission boundaries.</p>
+        </article>
+        <article>
+          <h2>Usage controls</h2>
+          <p>Track limits and metrics so your agent workflows stay predictable and cost-aware.</p>
+        </article>
+      </section>
+
+      <section class="api-first">
+        <div>
+          <h2>API-first by design</h2>
+          <p>
+            Base your integration on OpenAPI and use official SDKs for TypeScript and Python.
+            Build fast, then scale reliably.
+          </p>
+        </div>
+        <div class="api-links">
+          <a href="https://docs.emailagent.dev" data-cta="docs-api-section">Open API documentation</a>
+          <a href="https://www.npmjs.com/package/emailagent-sdk" data-cta="npm-sdk">TypeScript SDK on npm</a>
+          <a href="https://pypi.org/project/emailagent-sdk/" data-cta="pypi-sdk">Python SDK on PyPI</a>
+        </div>
+      </section>
+
+      <section id="pricing" class="pricing">
+        <h2>Simple pricing</h2>
+        <div class="pricing-grid">
+          <article class="plan">
+            <h3>Free</h3>
+            <p class="price">$0<span>/month</span></p>
+            <ul>
+              <li>1 inbox on shared domain</li>
+              <li>0 custom domains</li>
+              <li>1,000 outbound emails/month</li>
+              <li>API access included</li>
+            </ul>
+            <a class="button secondary" href="https://app.emailagent.dev/" data-cta="start-free-pricing">Start free</a>
+          </article>
+          <article class="plan featured">
+            <p class="badge">Most popular</p>
+            <h3>Paid</h3>
+            <p class="price">$10<span>/month</span></p>
+            <ul>
+              <li>10 inboxes</li>
+              <li>1 custom domain</li>
+              <li>10,000 outbound emails/month</li>
+              <li>Upgrade in-app with Dodo Payments</li>
+            </ul>
+            <a class="button primary" href="https://app.emailagent.dev/app/billing" data-cta="upgrade-pricing">Upgrade</a>
+          </article>
+        </div>
+      </section>
+    </main>
+
+    <footer class="footer">
+      <div>
+        <strong>EmailAgent</strong>
+        <p>Email infrastructure for AI agents.</p>
+      </div>
+      <div class="footer-links">
+        <a href="/privacy.html" data-cta="privacy">Privacy</a>
+        <a href="/terms.html" data-cta="terms">Terms</a>
+        <a href="mailto:support@emailagent.dev" data-cta="support">support@emailagent.dev</a>
+      </div>
+    </footer>
+  </body>
+</html>

package/landing/main.js

@@ -0,0 +1,45 @@
+(function () {
+  const analytics = window.__landingAnalytics || {};
+
+  function loadScript(src, attrs) {
+    const script = document.createElement('script');
+    script.src = src;
+    script.async = true;
+    Object.entries(attrs || {}).forEach(([k, v]) => script.setAttribute(k, v));
+    document.head.appendChild(script);
+  }
+
+  if (analytics.plausibleDomain) {
+    loadScript('https://plausible.io/js/script.js', {
+      defer: 'defer',
+      'data-domain': analytics.plausibleDomain
+    });
+  }
+
+  if (analytics.ga4MeasurementId) {
+    const id = analytics.ga4MeasurementId;
+    loadScript(`https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(id)}`);
+    window.dataLayer = window.dataLayer || [];
+    window.gtag = window.gtag || function gtag() {
+      window.dataLayer.push(arguments);
+    };
+    window.gtag('js', new Date());
+    window.gtag('config', id);
+  }
+
+  function trackCta(label) {
+    if (window.plausible) {
+      window.plausible('cta_click', { props: { label: label } });
+    }
+    if (window.gtag) {
+      window.gtag('event', 'cta_click', { label: label });
+    }
+  }
+
+  document.querySelectorAll('[data-cta]').forEach((node) => {
+    node.addEventListener('click', function onClick() {
+      const label = node.getAttribute('data-cta') || 'unknown';
+      trackCta(label);
+    });
+  });
+})();

package/landing/privacy.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Privacy Policy | EmailAgent</title>
+    <meta name="description" content="Privacy policy for EmailAgent." />
+    <link rel="canonical" href="https://emailagent.dev/privacy.html" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main style="max-width:900px;padding-top:28px;">
+      <a href="/" class="button ghost" style="display:inline-flex;margin-bottom:14px;">Back to home</a>
+      <section class="hero" style="padding:30px;">
+        <h1 style="font-size:40px;">Privacy Policy</h1>
+        <p class="lead">Last updated: February 9, 2026</p>
+        <h2 style="font-size:24px;">What we collect</h2>
+        <p class="lead">We collect account information (name, email), billing metadata, and email infrastructure metadata required to operate the service. We do not position EmailAgent as a personal email client.</p>
+        <h2 style="font-size:24px;">How we use data</h2>
+        <p class="lead">Data is used to provide inbox provisioning, domain onboarding, API key management, usage accounting, and abuse prevention.</p>
+        <h2 style="font-size:24px;">Subprocessors</h2>
+        <p class="lead">Email delivery and domain operations are handled through Mailgun. Billing is handled through Dodo Payments.</p>
+        <h2 style="font-size:24px;">Contact</h2>
+        <p class="lead">Questions: <a href="mailto:support@emailagent.dev">support@emailagent.dev</a></p>
+      </section>
+    </main>
+  </body>
+</html>