pi-cloudflare 0.1.0

package/skills/cloudflare/references/zaraz/gotchas.md

@@ -0,0 +1,81 @@
+# Zaraz Gotchas
+
+## Events Not Firing
+
+**Check:**
+1. Tool enabled in dashboard (green dot)
+2. Trigger conditions met
+3. Consent granted for tool's purpose
+4. Tool credentials correct (GA4: `G-XXXXXXXXXX`, FB: numeric only)
+
+**Debug:**
+```javascript
+zaraz.debug = true;
+console.log('Tools:', zaraz.tools);
+console.log('Consent:', zaraz.consent.getAll());
+```
+
+## Consent Issues
+
+**Modal not showing:**
+```javascript
+// Clear consent cookie
+document.cookie = 'zaraz-consent=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;';
+location.reload();
+```
+
+**Tools firing before consent:** Map tool to consent purpose with "Do not load until consent granted".
+
+## SPA Tracking
+
+**Route changes not tracked:**
+1. Configure History Change trigger in dashboard
+2. Hash routing (`#/path`) requires manual tracking:
+```javascript
+window.addEventListener('hashchange', () => {
+  zaraz.track('pageview', { page_path: location.pathname + location.hash });
+});
+```
+
+**React fix:**
+```javascript
+const location = useLocation();
+useEffect(() => {
+  zaraz.track('pageview', { page_path: location.pathname });
+}, [location]); // Include dependency
+```
+
+## Performance
+
+**Slow page load:**
+- Audit tool count (50+ degrades performance)
+- Disable blocking triggers unless required
+- Reduce event payload size (<100KB)
+
+## Tool-Specific Issues
+
+| Tool | Issue | Fix |
+|------|-------|-----|
+| GA4 | Events not in real-time | Wait 5-10 min, use DebugView |
+| Facebook | Invalid Pixel ID | Use numeric only (no `fbpx_` prefix) |
+| Google Ads | Conversions not attributed | Include `send_to: 'AW-XXX/LABEL'` |
+
+## Data Layer
+
+- Properties persist per page only - set on each page load
+- Nested access: `{{client.__zarazTrack.user.plan}}`
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Request size | 100KB |
+| Consent purposes | 20 |
+| API rate | 1000 req/sec |
+
+## When NOT to Use Zaraz
+
+- Server-to-server tracking (use Workers)
+- Real-time bidirectional communication
+- Binary data transmission
+- Authentication flows

package/skills/cloudflare/references/zaraz/patterns.md

@@ -0,0 +1,74 @@
+# Zaraz Patterns
+
+## SPA Tracking
+
+**History Change Trigger (Recommended):** Configure in dashboard - no code needed, Zaraz auto-detects route changes.
+
+**Manual tracking (React/Vue/Next.js):**
+```javascript
+// On route change
+zaraz.track('pageview', { page_path: pathname, page_title: document.title });
+```
+
+## User Identification
+
+```javascript
+// Login
+zaraz.set({ userId: user.id, email: user.email, plan: user.plan });
+zaraz.track('login', { method: 'oauth' });
+
+// Logout - set to null (cannot clear)
+zaraz.set('userId', null);
+```
+
+## E-commerce Funnel
+
+| Event | Method |
+|-------|--------|
+| View | `zaraz.ecommerce('Product Viewed', { product_id, name, price })` |
+| Add to cart | `zaraz.ecommerce('Product Added', { product_id, quantity })` |
+| Checkout | `zaraz.ecommerce('Checkout Started', { cart_id, products: [...] })` |
+| Purchase | `zaraz.ecommerce('Order Completed', { order_id, total, products })` |
+
+## A/B Testing
+
+```javascript
+zaraz.set('experiment_checkout', variant);
+zaraz.track('experiment_viewed', { experiment_id: 'checkout', variant });
+// On conversion
+zaraz.track('experiment_conversion', { experiment_id, variant, value });
+```
+
+## Worker Integration
+
+**Context Enricher** - Modify context before tools execute:
+```typescript
+export default {
+  async fetch(request, env) {
+    const body = await request.json();
+    body.system.userRegion = request.cf?.region;
+    return Response.json(body);
+  }
+};
+```
+Configure: Zaraz > Settings > Context Enrichers
+
+**Worker Variables** - Compute dynamic values server-side, use as `{{worker.variable_name}}`.
+
+## GTM Migration
+
+| GTM | Zaraz |
+|-----|-------|
+| `dataLayer.push({event: 'purchase'})` | `zaraz.ecommerce('Order Completed', {...})` |
+| `{{Page URL}}` | `{{system.page.url}}` |
+| `{{Page Title}}` | `{{system.page.title}}` |
+| Page View trigger | Pageview trigger |
+| Click trigger | Click (selector: `*`) |
+
+## Best Practices
+
+1. Use dashboard triggers over inline code
+2. Enable History Change for SPAs (no manual code)
+3. Debug with `zaraz.debug = true`
+4. Implement consent early (GDPR/CCPA)
+5. Use Context Enrichers for sensitive/server data

package/skills/cloudflare-email-service/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: cloudflare-email-service
+description: Send and receive transactional emails with Cloudflare Email Service (Email Sending + Email Routing). Use when building email sending (Workers binding or REST API), email routing, Agents SDK email handling, or integrating email into any app — Workers, Node.js, Python, Go, etc. Also use for email deliverability, SPF/DKIM/DMARC, wrangler email setup, MCP email tools, or when a coding agent needs to send emails. Even for simple requests like "add email to my Worker" — this skill has critical config details.
+---
+
+# Cloudflare Email Service
+
+Your knowledge of the Cloudflare Email Service, Email Routing or Email Sending may be outdated. **Prefer retrieval over pre-training** for any Cloudflare Email Service task.
+
+Cloudflare Email Service lets you send transactional emails and route incoming emails, all within the Cloudflare platform. Your knowledge of this product may be outdated — it launched in 2025 and is evolving rapidly. **Prefer retrieval over pre-training** for any Email Service task.
+
+**If there is any discrepancy between this skill and the sources below, always trust the original source.** The Cloudflare docs, REST API spec, `@cloudflare/workers-types`, and Agents SDK repo are the source of truth. This skill is a convenience guide — it may lag behind the latest changes. When in doubt, retrieve from the sources below and use what they say.
+
+## Retrieval Sources
+
+| Source | How to retrieve | Use for |
+|--------|----------------|---------|
+| Cloudflare docs | Cloudflare MCP `docs` tool or URL `https://developers.cloudflare.com/email-service/` | API reference, limits, pricing, latest features |
+| REST API spec | `https://developers.cloudflare.com/api/resources/email_sending` | OpenAPI spec for the Email Sending REST API |
+| Workers types | `https://www.npmjs.com/package/@cloudflare/workers-types` | Type signatures, binding shapes |
+| Agents SDK docs | Fetch `docs/email.md` from `https://github.com/cloudflare/agents/tree/main/docs` | Email handling in Agents SDK |
+
+## FIRST: Check Prerequisites
+
+Before writing any email code, verify the basics are in place:
+
+1. **Domain onboarded?** Run `npx wrangler email sending list` to see which domains have email sending enabled. If the domain isn't listed, run `npx wrangler email sending enable userdomain.com` or see [cli-and-mcp.md](references/cli-and-mcp.md) for full setup instructions.
+2. **Binding configured?** Look for `send_email` in `wrangler.jsonc` (for Workers)
+3. **postal-mime installed?** Run `npm ls postal-mime` (only needed for receiving/parsing emails)
+
+## What Do You Need?
+
+Start here. Find your situation, then follow the link for full details.
+
+| I want to... | Path | Reference |
+|--------------|------|-----------|
+| **Send emails from a Cloudflare Worker** | Workers binding (no API keys needed) | [sending.md](references/sending.md) |
+| **Send emails from an AI agent built with [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/)** | `onEmail()` + `replyToEmail()` in Agent class | [sending.md](references/sending.md) |
+| **Send emails from an external app or agent** (Node.js, Go, Python, etc.) | REST API with Bearer token | [rest-api.md](references/rest-api.md) |
+| **Send emails from a coding agent** (Claude Code, Cursor, Copilot, etc.) | MCP tools, wrangler CLI, or REST API | [cli-and-mcp.md](references/cli-and-mcp.md) |
+| **Receive and process incoming emails** (Email Routing) | Workers `email()` handler | [routing.md](references/routing.md) |
+| **Set up Email Sending or Email Routing** | `wrangler email sending enable` / `wrangler email routing enable`, or Dashboard | [cli-and-mcp.md](references/cli-and-mcp.md) |
+| **Improve deliverability, avoid spam folders** | Authentication, content, compliance | [deliverability.md](references/deliverability.md) |
+
+## Quick Start — Workers Binding
+
+Add the binding to `wrangler.jsonc`, then call `env.EMAIL.send()`. The `from` domain must be onboarded via `npx wrangler email sending enable yourdomain.com`.
+
+```jsonc
+// wrangler.jsonc
+{ "send_email": [{ "name": "EMAIL" }] }
+```
+
+```typescript
+const response = await env.EMAIL.send({
+  to: "user@example.com",
+  from: { email: "welcome@yourdomain.com", name: "My App" },
+  subject: "Welcome!",
+  html: "<h1>Welcome!</h1>",
+  text: "Welcome!",
+});
+```
+
+The binding is recommended for Workers — no API keys needed. If a user specifically requests the REST API from within a Worker (e.g., they already have an API token workflow), that works too — see [rest-api.md](references/rest-api.md).
+
+See [sending.md](references/sending.md) for the full API, batch sends, attachments, custom headers, restricted bindings, and Agents SDK integration.
+
+## Quick Start — REST API
+
+For apps outside Workers, or within Workers if the user explicitly requests it. Key differences from the Workers binding:
+
+- Endpoint: `POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send`
+- `from` object uses `address` (not `email`): `{ "address": "...", "name": "..." }`
+- `replyTo` is `reply_to` (snake_case)
+- Response returns `{ delivered: [], permanent_bounces: [], queued: [] }` (not `messageId`)
+
+See [rest-api.md](references/rest-api.md) for curl examples, response format, and error handling.
+
+## Common Mistakes
+
+| Mistake | Why It Happens | Fix |
+|---------|---------------|-----|
+| Forgetting `send_email` binding in wrangler config | Email Service uses a binding, not an API key | Add `"send_email": [{ "name": "EMAIL" }]` to wrangler.jsonc |
+| Sending from an unverified domain | Domain must be onboarded onto Email Sending before first send | Run `wrangler email sending enable yourdomain.com` or onboard in Dashboard |
+| Reading `message.raw` twice in email handler | The raw stream is single-use — second read returns empty | Buffer first: `const raw = await new Response(message.raw).arrayBuffer()` |
+| Missing `text` field (HTML only) | Some email clients only show plain text; also helps spam scores | Always include both `html` and `text` versions |
+| Using email for marketing/bulk sends | Email Service is for transactional email only | Use a dedicated marketing email platform for newsletters and campaigns |
+| Forwarding to unverified destinations | `message.forward()` only works with verified addresses | Run `wrangler email routing addresses create user@gmail.com` or add in Dashboard |
+| Testing with fake addresses | Bounces from non-existent addresses hurt sender reputation | Use real addresses you control during development |
+| Hardcoding API tokens in source code | Tokens in code get committed and leaked | Use environment variables or Cloudflare secrets |
+| Ignoring the `from` domain requirement | The `from` address must use a domain onboarded to Email Service | Verify the domain first, then send from `anything@that-domain.com` |
+| Using `email` key in REST API `from` object | REST API uses `address` not `email` for `from` object | Use `{ "address": "...", "name": "..." }` for REST, `{ "email": "...", "name": "..." }` for Workers |
+| Using `replyTo` in REST API | REST API uses snake_case field names | Use `reply_to` for REST API, `replyTo` for Workers binding |
+
+## References
+
+Read the reference that matches your situation. You don't need all of them.
+
+- **[references/sending.md](references/sending.md)** — Workers binding API, attachments, Agents SDK email. For Workers or Agents SDK.
+- **[references/rest-api.md](references/rest-api.md)** — REST endpoint, curl examples, error handling. For apps NOT on Workers.
+- **[references/routing.md](references/routing.md)** — Inbound `email()` handler, forwarding, replying, parsing. For receiving emails.
+- **[references/cli-and-mcp.md](references/cli-and-mcp.md)** — Domain setup, wrangler commands, MCP tools. For first-time setup.
+- **[references/deliverability.md](references/deliverability.md)** — SPF/DKIM/DMARC, bounces, suppressions, best practices.

package/skills/cloudflare-email-service/references/cli-and-mcp.md

@@ -0,0 +1,125 @@
+# CLI, MCP, and Project Setup
+
+Manage Cloudflare Email Service from the command line and coding agents.
+
+For full CLI reference, run `npx wrangler email --help`. For Dashboard setup, see the [getting started docs](https://developers.cloudflare.com/email-service/get-started/).
+
+## Wrangler Email Commands
+
+```
+wrangler email routing
+├── enable/disable   <domain>          # Toggle email routing
+├── dns get          <domain>          # Show required DNS records
+├── rules list/create/update/delete    # Manage routing rules
+└── addresses list/create/delete       # Destination addresses (account-scoped)
+
+wrangler email sending
+├── enable/disable   <domain>          # Toggle email sending
+├── dns get          <domain>          # Show sending DNS records (SPF, DKIM)
+├── send             --from --to ...   # Send an email (builder flags)
+└── send-raw         --from --to ...   # Send a raw MIME email
+```
+
+## Domain Setup
+
+### Via Dashboard
+
+1. Navigate to **Compute & AI** > **Email Service** > **Email Sending** (or **Email Routing**)
+2. Select **Onboard Domain** > choose domain > **Add records and onboard**
+
+This auto-adds SPF (TXT) and DKIM (CNAME/TXT) records. DNS usually propagates within 5-15 minutes.
+
+### Via CLI
+
+```bash
+npx wrangler email sending enable yourdomain.com
+npx wrangler email sending dns get yourdomain.com   # Verify records
+```
+
+## Local Development
+
+Add `"remote": true` to send real emails during `wrangler dev`:
+
+```jsonc
+{ "send_email": [{ "name": "EMAIL", "remote": true }] }
+```
+
+```bash
+npx wrangler dev
+```
+
+Emails are actually sent — use test addresses you control. Remove `"remote": true` before deploying.
+
+## Cloudflare MCP Server
+
+If you have the [Cloudflare MCP server](https://github.com/cloudflare/mcp) (`https://mcp.cloudflare.com/mcp`) configured, you can manage Email Service through its `search` and `execute` tools.
+
+Use `search` to find email sending endpoints:
+
+```javascript
+// search tool — find all email sending API endpoints
+async () => {
+  const results = [];
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    if (path.includes('email/sending')) {
+      for (const [method, op] of Object.entries(methods)) {
+        results.push({ method: method.toUpperCase(), path, summary: op.summary });
+      }
+    }
+  }
+  return results;
+}
+```
+
+Then use `execute` to call them — for example, checking sending limits or sending an email:
+
+```javascript
+// execute tool — check sending quota
+async () => {
+  return cloudflare.request({
+    method: "GET",
+    path: `/accounts/${accountId}/email/sending/limits`
+  });
+}
+
+// execute tool — send an email
+async () => {
+  return cloudflare.request({
+    method: "POST",
+    path: `/accounts/${accountId}/email/sending/send`,
+    body: {
+      to: "user@example.com",
+      from: { address: "notifications@yourdomain.com", name: "My App" },
+      subject: "Deployment Complete",
+      html: "<h1>Deployed!</h1>",
+      text: "Deployed!"
+    }
+  });
+}
+```
+
+GraphQL analytics queries also work through `execute` — see [deliverability.md](deliverability.md#graphql-analytics-api) for query examples. Note that email analytics are **zone-level** datasets (`emailSendingAdaptiveGroups`, `emailSendingAdaptive`) queried under `viewer > zones`, and require the **Analytics Read** token permission.
+
+## Sending from CLI / Agents
+
+```bash
+npx wrangler email sending send \
+  --from "agent@yourdomain.com" \
+  --to "developer@company.com" \
+  --subject "Deployment Complete" \
+  --text "Your Worker was deployed successfully."
+```
+
+Or via REST API:
+
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/email/sending/send" \
+  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "to": "developer@company.com",
+    "from": {"address": "agent@yourdomain.com", "name": "Build Agent"},
+    "subject": "Deployment Complete",
+    "text": "Your Worker was deployed successfully."
+  }'
+```

package/skills/cloudflare-email-service/references/deliverability.md

@@ -0,0 +1,285 @@
+# Email Deliverability & Best Practices
+
+For full details, see the [deliverability docs](https://developers.cloudflare.com/email-service/concepts/deliverability/) and [email authentication docs](https://developers.cloudflare.com/email-service/concepts/email-authentication/). All the monitoring endpoints below can be called via the [REST API](rest-api.md), [Wrangler CLI, or the Cloudflare MCP server](cli-and-mcp.md).
+
+## What Cloudflare Handles
+
+When you onboard a domain, Cloudflare auto-configures:
+
+- **SPF** — TXT records authorizing Cloudflare's sending infrastructure
+- **DKIM** — Records for cryptographic signing of outbound emails
+- **IP reputation** — Managed sending infrastructure optimized for deliverability
+- **Soft bounce retries** — Automatic exponential backoff for temporary failures
+- **Suppression lists** — Hard-bounced addresses automatically blocked
+- **Feedback loops** — ISP complaint signals processed and acted on
+
+Consider adding a **DMARC** record if you don't have one: `v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourdomain.com`
+
+## Bounce Handling
+
+**Hard bounces** — permanent failures (address doesn't exist, domain doesn't exist). Never retried. Address auto-added to suppression list. Sending to suppressed address returns `E_RECIPIENT_SUPPRESSED`.
+
+**Soft bounces** — temporary failures (mailbox full, server down, greylisting). Cloudflare auto-retries with exponential backoff.
+
+## Suppression Lists
+
+**Account list** (your account) — spam complaints from recipients. Cloudflare integrates with Postmasters to auto-suppress. You can manually add/remove addresses in the Dashboard.
+
+See the [suppressions docs](https://developers.cloudflare.com/email-service/concepts/suppressions/) for details.
+
+## Your Responsibilities
+
+### Content
+- Include both HTML and plain text versions
+- Use a recognizable sender name: `{ email: "noreply@app.com", name: "My App" }`
+- Write honest subject lines — avoid ALL CAPS, excessive punctuation
+- Include `List-Unsubscribe` headers for recurring emails
+- Use full URLs from your domain — avoid URL shorteners
+
+### List Quality
+- Validate email addresses before sending
+- Implement double opt-in for subscriptions
+- Honor unsubscribe requests promptly
+
+### Transactional Only
+Email Service is for **transactional email** (triggered by user actions: signups, password resets, order confirmations). Marketing/bulk campaigns are not permitted — use a dedicated marketing platform.
+
+## Monitoring Deliverability
+
+### Dashboard
+
+Per-domain and account-wide analytics are available in the Cloudflare dashboard:
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
+2. Go to **Compute & AI** > **Email Service**.
+3. Select a domain or view account-wide metrics.
+4. Select the **Analytics** tab.
+
+### Send Response
+
+Every send (REST API or Workers binding) returns immediate delivery feedback. Check the response to track per-send outcomes:
+
+```json
+{
+  "result": {
+    "delivered": ["user@example.com"],
+    "permanent_bounces": ["bad@nonexistent.com"],
+    "queued": ["slow@recipient.com"]
+  }
+}
+```
+
+Log these to build your own delivery rate metrics.
+
+### Sending Limits
+
+Check your account's daily sending quota:
+
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/limits" \
+  --header "Authorization: Bearer <API_TOKEN>"
+```
+
+Returns:
+
+```json
+{
+  "result": {
+    "quota": { "value": 5000, "unit": "day" }
+  }
+}
+```
+
+### Suppression List
+
+Addresses that hard-bounced or received spam complaints are auto-suppressed. You can query and manage suppressions via the API.
+
+**List suppressions (account-wide):**
+
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/suppression?page=1&per_page=100&order=created_at&direction=desc" \
+  --header "Authorization: Bearer <API_TOKEN>"
+```
+
+Returns:
+
+```json
+{
+  "page": 1,
+  "per_page": 100,
+  "total": 2,
+  "result": [
+    {
+      "id": "396a5436-d4b0-42a6-b3fc-48e8fa522321",
+      "email": "bounced@example.com",
+      "reason": "hard_bounce",
+      "created_at": "2026-03-15T10:00:00Z",
+      "expires_at": null
+    }
+  ]
+}
+```
+
+Query params: `page`, `per_page` (max 1000), `order` (`email` | `expires_at` | `created_at`), `direction` (`asc` | `desc`).
+
+**Manually suppress an address:**
+
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/suppression" \
+  --header "Authorization: Bearer <API_TOKEN>" \
+  --header "Content-Type: application/json" \
+  --data '{ "email": "user@example.com", "expires_at": "2026-06-01T00:00:00Z" }'
+```
+
+`expires_at` is optional — omit for permanent suppression.
+
+**Remove a suppression:**
+
+```bash
+curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/suppression/{suppression_id}" \
+  --header "Authorization: Bearer <API_TOKEN>"
+```
+
+Zone-level suppressions are also available at `/zones/{zone_id}/email/sending/suppression` with the same interface.
+
+### GraphQL Analytics API
+
+Email Service exposes two zone-level datasets via the [GraphQL Analytics API](https://developers.cloudflare.com/analytics/graphql-api/). You can explore the schema interactively at [graphql.cloudflare.com/explorer](https://graphql.cloudflare.com/explorer). Metrics are retained for 31 days.
+
+| Dataset | Description |
+|---------|-------------|
+| `emailSendingAdaptiveGroups` | Aggregated counts grouped by dimensions (status, date, domain, auth results, etc.) |
+| `emailSendingAdaptive` | Individual email events with full detail (from, to, subject, messageId, errors, etc.) |
+
+These are **zone-level** datasets — query under `viewer > zones`, not `accounts`.
+
+**Aggregated dimensions** (`emailSendingAdaptiveGroups`):
+
+| Dimension | Type | Description |
+|-----------|------|-------------|
+| `date` | Date | Day-level grouping |
+| `datetime` | Time | Exact timestamp (also: `datetimeMinute`, `datetimeFiveMinutes`, `datetimeFifteenMinutes`, `datetimeHour`) |
+| `status` | string | Delivery status |
+| `eventType` | string | Event type |
+| `sendingDomain` | string | The sending domain |
+| `envelopeTo` | string | Recipient address |
+| `errorCause` | string | Error cause for failed sends |
+| `arc`, `dkim`, `dmarc`, `spf` | string | Email authentication results |
+| `isSpam`, `isNDR`, `isLastEvent` | uint8 | Boolean flags |
+| `spamScore`, `spamThreshold` | uint32 | Spam scoring |
+
+**Individual event fields** (`emailSendingAdaptive`) additionally include: `from`, `to`, `subject`, `messageId`, `sessionId`, `errorDetail`.
+
+**Email counts by status and date:**
+
+```graphql
+query EmailSendingByStatus(
+  $zoneTag: string!
+  $start: Date!
+  $end: Date!
+) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      emailSendingAdaptiveGroups(
+        filter: { date_geq: $start, date_leq: $end }
+        limit: 10000
+        orderBy: [date_DESC]
+      ) {
+        count
+        dimensions {
+          date
+          status
+        }
+      }
+    }
+  }
+}
+```
+
+**Filter by status (e.g. only failures):**
+
+```graphql
+query EmailFailures(
+  $zoneTag: string!
+  $start: Date!
+  $end: Date!
+) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      emailSendingAdaptiveGroups(
+        filter: { date_geq: $start, date_leq: $end, status: "deliveryFailed" }
+        limit: 10000
+        orderBy: [date_DESC]
+      ) {
+        count
+        dimensions {
+          date
+          errorCause
+          sendingDomain
+        }
+      }
+    }
+  }
+}
+```
+
+**Individual email events (troubleshooting):**
+
+```graphql
+query RecentEmailEvents(
+  $zoneTag: string!
+  $start: Time!
+  $end: Time!
+) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      emailSendingAdaptive(
+        filter: { datetime_geq: $start, datetime_leq: $end }
+        limit: 50
+        orderBy: [datetime_DESC]
+      ) {
+        datetime
+        from
+        to
+        subject
+        status
+        eventType
+        sendingDomain
+        messageId
+        errorCause
+        errorDetail
+        dkim
+        dmarc
+        spf
+        isSpam
+      }
+    }
+  }
+}
+```
+
+Note: `emailSendingAdaptive` filters use `datetime_geq`/`datetime_leq` (Time type, e.g. `"2026-04-01T00:00:00Z"`), while `emailSendingAdaptiveGroups` uses `date_geq`/`date_leq` (Date type, e.g. `"2026-04-01"`).
+
+**curl example:**
+
+```bash
+curl "https://api.cloudflare.com/client/v4/graphql" \
+  --header "Authorization: Bearer <API_TOKEN>" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "query": "query($zoneTag:string!,$start:Date!,$end:Date!){viewer{zones(filter:{zoneTag:$zoneTag}){emailSendingAdaptiveGroups(filter:{date_geq:$start,date_leq:$end},limit:10000,orderBy:[date_DESC]){count,dimensions{date,status}}}}}",
+    "variables": {
+      "zoneTag": "<ZONE_ID>",
+      "start": "2026-03-15",
+      "end": "2026-04-15"
+    }
+  }'
+```
+
+## Metrics to Watch
+
+| Metric | Target | If Out of Range |
+|--------|--------|-----------------|
+| Delivery rate | > 95% | Check for invalid addresses; verify DNS records |
+| Hard bounce rate | < 2% | Clean your email list |
+| Complaint rate | < 0.1% | Make unsubscribe easier; stop unwanted emails |