vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/resend/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: resend
+description: Use when working with the Resend email API — sending transactional emails (single or batch), receiving inbound emails via webhooks, managing email templates, tracking delivery events, managing domains, contacts, broadcasts, webhooks, API keys, automations, events, viewing API request logs, or setting up the Resend SDK. Always use this skill when the user mentions Resend, even for simple tasks like "send an email with Resend" — the skill contains critical gotchas (idempotency keys, webhook verification, template variable syntax) that prevent common production issues.
+license: MIT
+metadata:
+    author: resend
+    version: "3.5.0"
+    homepage: https://resend.com/agent-skills
+    source: https://github.com/resend/resend-skills
+    openclaw:
+        primaryEnv: RESEND_API_KEY
+        requires:
+            env:
+                - RESEND_API_KEY
+        envVars:
+            - name: RESEND_API_KEY
+              required: true
+              description: Resend API key for sending and receiving emails
+            - name: RESEND_WEBHOOK_SECRET
+              required: false
+              description: Webhook signing secret for verifying event payloads
+        links:
+            repository: https://github.com/resend/resend-skills
+            documentation: https://resend.com/docs/resend-skill
+inputs:
+    - name: RESEND_API_KEY
+      description: Resend API key for sending and receiving emails. Get yours at https://resend.com/api-keys
+      required: true
+    - name: RESEND_WEBHOOK_SECRET
+      description: Webhook signing secret for verifying event payloads. Found in the Resend dashboard under Webhooks after creating an endpoint.
+      required: false
+references:
+    - sending
+    - receiving.md
+    - templates.md
+    - webhooks.md
+    - domains.md
+    - contacts.md
+    - broadcasts.md
+    - api-keys.md
+    - logs.md
+    - contact-properties.md
+    - segments.md
+    - topics.md
+    - automations.md
+    - events.md
+    - installation.md
+    - fetch-all-templates.mjs
+---
+
+# Resend
+
+## Quick Send — Node.js
+
+```typescript
+import { Resend } from 'resend';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+const { data, error } = await resend.emails.send(
+  {
+    from: 'Acme <onboarding@resend.dev>',
+    to: ['delivered@resend.dev'],
+    subject: 'Hello World',
+    html: '<p>Email body here</p>',
+  },
+  { idempotencyKey: `welcome-email/${userId}` }
+);
+
+if (error) {
+  console.error('Failed:', error.message);
+  return;
+}
+console.log('Sent:', data.id);
+```
+
+**Key gotcha:** The Resend Node.js SDK does NOT throw exceptions — it returns `{ data, error }`. Always check `error` explicitly instead of using try/catch for API errors.
+
+## Quick Send — Python
+
+```python
+import resend
+import os
+
+resend.api_key = os.environ["RESEND_API_KEY"]
+
+email = resend.Emails.send({
+    "from": "Acme <onboarding@resend.dev>",
+    "to": ["delivered@resend.dev"],
+    "subject": "Hello World",
+    "html": "<p>Email body here</p>",
+}, idempotency_key=f"welcome-email/{user_id}")
+```
+
+### Single vs Batch Decision
+
+| Choose | When |
+|--------|------|
+| **Single** (`POST /emails`) | 1 email, needs attachments, needs scheduling |
+| **Batch** (`POST /emails/batch`) | 2-100 distinct emails, no attachments, no scheduling |
+
+Batch is atomic — if one email fails validation, the entire batch fails. Always validate before sending. Batch does NOT support attachments or `scheduled_at`.
+
+### Idempotency Keys (Critical for Retries)
+
+Prevent duplicate emails when retrying failed requests:
+
+| Key Facts | |
+|-----------|---|
+| **Format (single)** | `<event-type>/<entity-id>` (e.g., `welcome-email/user-123`) |
+| **Format (batch)** | `batch-<event-type>/<batch-id>` (e.g., `batch-orders/batch-456`) |
+| **Expiration** | 24 hours |
+| **Max length** | 256 characters |
+| **Same key + same payload** | Returns original response without resending |
+| **Same key + different payload** | Returns 409 error |
+
+## Quick Receive (Node.js)
+
+```typescript
+import { Resend } from 'resend';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function POST(req: Request) {
+  const payload = await req.text(); // Must use raw text, not req.json()
+
+  const event = resend.webhooks.verify({
+    payload,
+    headers: {
+      'svix-id': req.headers.get('svix-id'),
+      'svix-timestamp': req.headers.get('svix-timestamp'),
+      'svix-signature': req.headers.get('svix-signature'),
+    },
+    secret: process.env.RESEND_WEBHOOK_SECRET,
+  });
+
+  if (event.type === 'email.received') {
+    // Webhook has metadata only — call API for body
+    const { data: email } = await resend.emails.receiving.get(
+      event.data.email_id
+    );
+    console.log(email.text);
+  }
+
+  return new Response('OK', { status: 200 });
+}
+```
+
+**Key gotcha:** Webhook payloads do NOT contain the email body. You must call `resend.emails.receiving.get()` separately.
+
+## What Do You Need?
+
+| Task | Reference |
+|------|-----------|
+| **Send a single email** | [sending/overview.md](references/sending/overview.md) — parameters, deliverability, testing |
+| **Send batch emails** | [sending/overview.md](references/sending/overview.md) → [sending/batch-email-examples.md](references/sending/batch-email-examples.md) |
+| **Full SDK examples** (Node.js, Python, Go, cURL) | [sending/single-email-examples.md](references/sending/single-email-examples.md) |
+| **Idempotency, retries, error handling** | [sending/best-practices.md](references/sending/best-practices.md) |
+| **Get, list, reschedule, cancel emails** | [sending/email-management.md](references/sending/email-management.md) |
+| **Receive inbound emails** | [receiving.md](references/receiving.md) — domain setup, webhooks, attachments |
+| **Manage templates** (CRUD, variables) | [templates.md](references/templates.md) — lifecycle, aliases, pagination |
+| **Set up webhooks** (events, verification) | [webhooks.md](references/webhooks.md) — verification, CRUD, retry schedule, IP allowlist |
+| **Manage domains** (create, verify, claim, DNS) | [domains.md](references/domains.md) — regions, TLS, tracking, claiming, capabilities |
+| **Manage contacts** (CRUD, properties) | [contacts.md](references/contacts.md) — segments, topics, custom properties, bulk CSV import |
+| **Send broadcasts** (marketing campaigns) | [broadcasts.md](references/broadcasts.md) — lifecycle, scheduling, template variables |
+| **Manage API keys** | [api-keys.md](references/api-keys.md) — permission scoping, domain restrictions |
+| **View API request logs** | [logs.md](references/logs.md) — list and retrieve API call history, debugging |
+| **Define contact properties** | [contact-properties.md](references/contact-properties.md) — custom fields for contacts |
+| **Manage segments** (contact groups) | [segments.md](references/segments.md) — broadcast targeting, contact grouping |
+| **Manage topics** (subscriptions) | [topics.md](references/topics.md) — opt-in/out preferences, broadcast filtering |
+| **Create automations** (event-driven workflows) | [automations.md](references/automations.md) — steps, connections, runs, conditions |
+| **Define and send events** (automation triggers) | [events.md](references/events.md) — schemas, payloads, contact association |
+| **Install SDK** (8+ languages) | [installation.md](references/installation.md) |
+| **Set up an AI agent inbox** | Install the `agent-email-inbox` skill — covers security levels for untrusted input |
+
+## SDK Version Requirements
+
+Always install the latest SDK version. These are the minimum versions for full functionality (sending, receiving, webhook verification):
+
+| Language | Package | Min Version | Install |
+|----------|---------|-------------|---------|
+| Node.js | `resend` | >= 6.14.0 | `npm install resend` |
+| Python | `resend` | >= 2.21.0 | `pip install resend` |
+| Go | `resend-go/v3` | >= 3.1.0 | `go get github.com/resend/resend-go/v3` |
+| Ruby | `resend` | >= 1.0.0 | `gem install resend` |
+| PHP | `resend/resend-php` | >= 1.1.0 | `composer require resend/resend-php` |
+| Rust | `resend-rs` | >= 0.20.0 | `cargo add resend-rs` |
+| Java | `resend-java` | >= 4.11.0 | See [installation.md](references/installation.md) |
+| .NET | `Resend` | >= 0.2.1 | `dotnet add package Resend` |
+
+> **If the project already has a Resend SDK installed**, check the version and upgrade if it's below the minimum. Older SDKs may be missing `webhooks.verify()`, `emails.receiving.get()`, or `domains.claims.*`.
+
+See [installation.md](references/installation.md) for full installation commands, language detection, and cURL fallback.
+
+## Common Setup
+
+### API Key
+
+Store in environment variable — never hardcode:
+```bash
+export RESEND_API_KEY=re_xxxxxxxxx
+```
+
+Get your key at [resend.com/api-keys](https://resend.com/api-keys).
+
+### Detect Project Language
+
+Check for these files: `package.json` (Node.js), `requirements.txt`/`pyproject.toml` (Python), `go.mod` (Go), `Gemfile` (Ruby), `composer.json` (PHP), `Cargo.toml` (Rust), `pom.xml`/`build.gradle` (Java), `*.csproj` (.NET).
+
+## Common Mistakes
+
+| # | Mistake | Fix |
+|---|---------|-----|
+| 1 | **Retrying without idempotency key** | Always include idempotency key — prevents duplicate sends on retry. Format: `<event-type>/<entity-id>` |
+| 2 | **Not verifying webhook signatures** | Always verify with `resend.webhooks.verify()` — unverified events can't be trusted |
+| 3 | **Template variable name mismatch** | Variable names are case-sensitive — must match the template definition exactly. Use triple mustache `{{{VAR}}}` syntax |
+| 4 | **Expecting email body in webhook payload** | Webhooks contain metadata only — call `resend.emails.receiving.get()` for body content |
+| 5 | **Using try/catch for Node.js SDK errors** | SDK returns `{ data, error }` — check `error` explicitly, don't wrap in try/catch |
+| 6 | **Using batch for emails with attachments** | Batch doesn't support attachments — use single sends instead |
+| 7 | **Testing with fake emails (test@gmail.com)** | Use `delivered@resend.dev` — fake addresses bounce and hurt reputation |
+| 8 | **Sending with draft template** | Templates must be published before sending — call `.publish()` first |
+| 9 | **`html` + `template` in same send call** | Mutually exclusive — remove `html`/`text`/`react` when using template |
+| 10 | **MX record not lowest priority for inbound** | Ensure Resend's MX has the lowest number (highest priority) or emails won't route |
+| 11 | **403 when sending from `resend.dev`** | The default `onboarding@resend.dev` is a sandbox — it can only deliver to your Resend account email. Verify your own domain first |
+| 12 | **403 domain mismatch** | The `from` address domain must exactly match a verified domain. Verified `send.acme.com` but sending from `user@acme.com` will fail |
+| 13 | **Calling Resend API from the browser (CORS)** | The API does not support CORS — this is intentional to protect your API key. Always call from server-side (API routes, serverless functions) |
+| 14 | **401 `restricted_api_key`** | A sending-only API key was used on a non-sending endpoint (domains, contacts, etc.). Create a full-access key instead |
+
+## Cross-Cutting Concerns
+
+### Send + Receive Together
+
+Auto-replies, email forwarding, or any receive-then-send workflow requires both capabilities:
+1. Set up inbound domain first (see [receiving.md](references/receiving.md))
+2. Set up sending (see [sending/overview.md](references/sending/overview.md))
+3. Note: batch sending does NOT support attachments or scheduling — use single sends when forwarding with attachments
+
+### AI Agent Inbox
+
+If your system processes untrusted email content and takes actions (refunds, database changes, forwarding), install the `agent-email-inbox` skill. This applies whether or not AI is involved — any system interpreting freeform email content from external senders needs security measures.
+
+### Marketing Emails
+
+The sending capabilities in this skill are for **transactional email** (receipts, confirmations, notifications). For marketing campaigns to large subscriber lists with unsubscribe links and engagement tracking, use Resend Broadcasts — see [broadcasts.md](references/broadcasts.md) for the API.
+
+### Domain Warm-up
+
+New domains must gradually increase sending volume. Day 1 limit: ~150 emails (new domain) or ~1,000 (existing domain). See the warm-up schedule in [sending/overview.md](references/sending/overview.md).
+
+### Testing
+
+**Never test with fake addresses at real email providers** (test@gmail.com, fake@outlook.com) — they bounce and destroy sender reputation.
+
+| Address | Result |
+|---------|--------|
+| `delivered@resend.dev` | Simulates successful delivery |
+| `bounced@resend.dev` | Simulates hard bounce |
+| `complained@resend.dev` | Simulates spam complaint |
+
+### Suppression List
+
+Resend automatically suppresses hard-bounced and spam-complained addresses. Sending to suppressed addresses fires the `email.suppressed` webhook event instead of attempting delivery. Manage in Dashboard → Suppressions.
+
+### Webhook Event Types
+
+| Event | Trigger |
+|-------|---------|
+| `email.sent` | API request successful |
+| `email.delivered` | Reached recipient's mail server |
+| `email.bounced` | Permanently rejected (hard bounce) |
+| `email.complained` | Recipient marked as spam |
+| `email.opened` / `email.clicked` | Recipient engagement |
+| `email.delivery_delayed` | Soft bounce, Resend retries |
+| `email.received` | Inbound email arrived |
+| `domain.*` / `contact.*` | Domain/contact changes |
+
+See [webhooks.md](references/webhooks.md) for full details, signature verification, and retry schedule.
+
+## Error Handling Quick Reference
+
+| Code | Action |
+|------|--------|
+| 400, 422 | Fix request parameters, don't retry |
+| 401 | Check API key — `restricted_api_key` means sending-only key used on non-sending endpoint |
+| 403 | Verify domain ownership — common causes: `resend.dev` sandbox, `from` domain mismatch, unverified domain |
+| 409 | Idempotency conflict — use new key or fix payload |
+| 429 | Rate limited — retry with exponential backoff (default rate limit: 2 req/s) |
+| 500 | Server error — retry with exponential backoff |
+
+## Resources
+
+- [Resend Documentation](https://resend.com/docs)
+- [API Reference](https://resend.com/docs/api-reference)
+- [Dashboard](https://resend.com/emails)

package/dist/global-skills/resend/references/api-keys.md

@@ -0,0 +1,98 @@
+# API Keys
+
+Create, list, and delete API keys programmatically. No get or update endpoints exist.
+
+## SDK Methods
+
+| Operation | Node.js | Python |
+|-----------|---------|--------|
+| Create | `resend.apiKeys.create(params)` | `resend.ApiKeys.create(params)` |
+| List | `resend.apiKeys.list(params?)` | `resend.ApiKeys.list()` |
+| Delete | `resend.apiKeys.remove(id)` | `resend.ApiKeys.remove(id)` |
+
+## Create Parameters
+
+**Required:** `name`
+
+**Optional:** `permission`, `domainId`
+
+- `permission`: `"full_access"` (default) or `"sending_access"`
+- `domainId`: only applies when `permission` is `"sending_access"` — scopes the key to a single domain
+- `name`: max 50 characters
+
+## Examples
+
+### Node.js
+
+```typescript
+import { Resend } from 'resend';
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+// Create a domain-scoped sending key
+const { data, error } = await resend.apiKeys.create({
+  name: 'Production Sending Key',
+  permission: 'sending_access',
+  domainId: 'd_abc123',
+});
+
+if (error) {
+  console.error(error);
+  return;
+}
+
+// IMPORTANT: This is the only time the token is returned -- store it now
+console.log('API Key:', data.token);  // re_xxxxxxxxx
+console.log('Key ID:', data.id);
+
+// List all keys (tokens are NOT included in list response)
+const { data: keys, error: listError } = await resend.apiKeys.list();
+
+// Delete a key
+const { data: deleted, error: deleteError } = await resend.apiKeys.remove('api_key_id');
+```
+
+### Python
+
+```python
+import resend
+
+resend.api_key = "re_xxxxxxxxx"
+
+# Create a domain-scoped sending key
+key = resend.ApiKeys.create({
+    "name": "Production Sending Key",
+    "permission": "sending_access",
+    "domain_id": "d_abc123",
+})
+
+# IMPORTANT: Store the token immediately
+print(f"API Key: {key['token']}")
+
+# List all keys
+keys = resend.ApiKeys.list()
+
+# Delete a key
+resend.ApiKeys.remove("api_key_id")
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Not storing the token on create | The token is returned **once** — store it immediately |
+| Expecting a get or update endpoint | Neither exists — list returns metadata only (no tokens) |
+| Setting `domainId` with `full_access` | `domainId` only applies to `sending_access` keys |
+| Calling `.delete()` instead of `.remove()` | Node.js SDK uses `.remove()` for all delete operations |
+| Ignoring `error` return | Node.js SDK returns `{ data, error }` — always check `error` |
+| Name over 50 characters | `name` has a 50-character limit |
+
+## Response Fields
+
+List returns metadata for each key:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | API key ID |
+| `name` | string | Display name |
+| `created_at` | string | Creation timestamp |
+| `last_used_at` | string \| null | Last time the key was used (null if never used) |

package/dist/global-skills/resend/references/automations.md

@@ -0,0 +1,228 @@
+# Automations
+
+## Overview
+
+Automations are event-driven workflows composed of steps connected in a directed graph. Each automation has a trigger step that starts the flow, followed by action steps (send email, delay, wait for event, condition, contact update, contact delete, add to segment).
+
+Automations are created in a `disabled` state by default. Set `status: "enabled"` to activate.
+
+## SDK Methods
+
+### Node.js
+
+| Operation | Method | Notes |
+|-----------|--------|-------|
+| Create | `resend.automations.create(params)` | Returns automation ID |
+| Get | `resend.automations.get(id)` | Returns full automation with steps and connections |
+| List | `resend.automations.list(params?)` | Filter by `status`, cursor-paginated |
+| Update | `resend.automations.update(params)` | Partial update — name, status, or steps+connections |
+| Delete | `resend.automations.remove(id)` | Permanent |
+| Stop | `resend.automations.stop(id)` | Sets status to `disabled` |
+| List Runs | `resend.automations.runs.list({ automationId, status? })` | Filter by run status |
+| Get Run | `resend.automations.runs.get({ automationId, runId })` | Returns run with executed steps |
+
+### Python
+
+`resend.Automations.create/get/list/update/remove/stop` — same operations with snake_case params.
+
+## Graph Model
+
+An automation is a directed graph of **steps** connected by **connections**.
+
+### Steps
+
+Each step has a `key` (unique within the graph), a `type`, and a `config` object whose shape depends on the type.
+
+| Type | Config | Description |
+|------|--------|-------------|
+| `trigger` | `{ event_name: string }` | Entry point — fires when the named event occurs |
+| `send_email` | `{ template: { id: string, variables?: object }, subject?: string, from?: string, reply_to?: string }` | Sends an email using a published template |
+| `delay` | `{ duration: string }` | Pauses the run. `duration` is human-readable (e.g. `"30 minutes"`, `"3 days"`) |
+| `wait_for_event` | `{ event_name: string, timeout?: string, filter_rule?: object }` | Waits for an event. `timeout` is human-readable (e.g. `"1 hour"`). `filter_rule` uses the same rule tree as `condition` but restricted to `event.*` fields |
+| `condition` | Rule tree (see below) | Branches based on contact data |
+| `contact_update` | `{ first_name?, last_name?, unsubscribed?, properties? }` | Updates the contact |
+| `contact_delete` | `{}` | Deletes the contact |
+| `add_to_segment` | `{ segment_id: string }` | Adds the contact to a segment |
+
+### Rule Tree (condition & filter_rule)
+
+Leaf nodes: `{ "type": "rule", "field": "<namespace>.<key>", "operator": "<op>", "value": "<val>" }`
+
+Groups: `{ "type": "and" | "or", "rules": [...] }` for nesting.
+
+Supported operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, `ends_with`, `exists`, `is_empty`. The `exists` and `is_empty` operators require no `value`.
+
+For `condition` steps, fields reference contact data (e.g. `properties.plan`). For `filter_rule` in `wait_for_event`, fields are restricted to `event.*` (e.g. `event.status`).
+
+### Connections
+
+Connections link steps by their `key`. Each connection has a `type`:
+
+| Connection Type | Use |
+|-----------------|-----|
+| `default` | Normal flow between steps |
+| `condition_met` | Branch when condition is true |
+| `condition_not_met` | Branch when condition is false |
+| `timeout` | Branch when `wait_for_event` times out |
+| `event_received` | Branch when `wait_for_event` receives the event |
+
+## Examples
+
+### Create an Automation
+
+```typescript
+const { data, error } = await resend.automations.create({
+  name: 'Welcome Series',
+  status: 'enabled',
+  steps: [
+    {
+      key: 'trigger_signup',
+      type: 'trigger',
+      config: { event_name: 'user.signed_up' },
+    },
+    {
+      key: 'send_welcome',
+      type: 'send_email',
+      config: {
+        template: { id: 'tmpl_abc123' },
+        from: 'Acme <hello@acme.com>',
+        subject: 'Welcome to Acme!',
+      },
+    },
+    {
+      key: 'wait_3_days',
+      type: 'delay',
+      config: { duration: '3 days' },
+    },
+    {
+      key: 'send_followup',
+      type: 'send_email',
+      config: {
+        template: { id: 'tmpl_def456' },
+        from: 'Acme <hello@acme.com>',
+        subject: 'Getting started with Acme',
+      },
+    },
+  ],
+  connections: [
+    { from: 'trigger_signup', to: 'send_welcome' },
+    { from: 'send_welcome', to: 'wait_3_days' },
+    { from: 'wait_3_days', to: 'send_followup' },
+  ],
+});
+```
+
+```python
+automation = resend.Automations.create({
+    "name": "Welcome Series",
+    "status": "enabled",
+    "steps": [
+        {"key": "trigger_signup", "type": "trigger", "config": {"event_name": "user.signed_up"}},
+        {"key": "send_welcome", "type": "send_email", "config": {
+            "template": {"id": "tmpl_abc123"},
+            "from": "Acme <hello@acme.com>",
+            "subject": "Welcome to Acme!",
+        }},
+        {"key": "wait_3_days", "type": "delay", "config": {"duration": "3 days"}},
+        {"key": "send_followup", "type": "send_email", "config": {
+            "template": {"id": "tmpl_def456"},
+            "from": "Acme <hello@acme.com>",
+            "subject": "Getting started with Acme",
+        }},
+    ],
+    "connections": [
+        {"from": "trigger_signup", "to": "send_welcome"},
+        {"from": "send_welcome", "to": "wait_3_days"},
+        {"from": "wait_3_days", "to": "send_followup"},
+    ],
+})
+```
+
+### Conditional Branching
+
+```typescript
+const { data, error } = await resend.automations.create({
+  name: 'Onboarding with condition',
+  status: 'enabled',
+  steps: [
+    { key: 'trigger', type: 'trigger', config: { event_name: 'user.signed_up' } },
+    {
+      key: 'check_plan',
+      type: 'condition',
+      config: { type: 'rule', field: 'properties.plan', operator: 'equals', value: 'pro' },
+    },
+    { key: 'send_pro', type: 'send_email', config: { template: { id: 'tmpl_pro' }, from: 'Acme <hello@acme.com>' } },
+    { key: 'send_free', type: 'send_email', config: { template: { id: 'tmpl_free' }, from: 'Acme <hello@acme.com>' } },
+  ],
+  connections: [
+    { from: 'trigger', to: 'check_plan' },
+    { from: 'check_plan', to: 'send_pro', type: 'condition_met' },
+    { from: 'check_plan', to: 'send_free', type: 'condition_not_met' },
+  ],
+});
+```
+
+### Update an Automation
+
+When updating the workflow graph, both `steps` and `connections` must be provided together. You can update `name` or `status` independently.
+
+```typescript
+// Enable/disable without changing the graph
+const { data, error } = await resend.automations.update({
+  id: 'aut_abc123',
+  status: 'disabled',
+});
+```
+
+```typescript
+// Update the full graph (steps + connections required together)
+const { data, error } = await resend.automations.update({
+  id: 'aut_abc123',
+  steps: [/* full step array */],
+  connections: [/* full connections array */],
+});
+```
+
+### List and Monitor Runs
+
+```typescript
+// List runs, optionally filter by status
+const { data: runs } = await resend.automations.runs.list({
+  automationId: 'aut_abc123',
+  status: 'running,failed',  // comma-separated: running, completed, failed, cancelled
+});
+
+// Get a specific run with executed step details
+const { data: run } = await resend.automations.runs.get({
+  automationId: 'aut_abc123',
+  runId: 'run_def456',
+});
+// run.steps[].status, run.steps[].output, run.steps[].error
+```
+
+### Stop an Automation
+
+```typescript
+const { data, error } = await resend.automations.stop('aut_abc123');
+// data.status === 'disabled'
+```
+
+## Constraints
+
+- Max **150 steps** per automation
+- At least **one trigger step** required
+- Steps and connections must be provided **together** when updating the graph
+- `key` must be unique within the automation
+- Connections reference steps by `key`
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Creating without a trigger step | Every automation needs at least one step with `type: "trigger"` |
+| Updating steps without connections (or vice versa) | When changing the graph, provide both `steps` and `connections` together |
+| Using `ref` or `edges` (old naming) | Use `key` for step identifiers and `connections` for links between steps |
+| Using `template_id` in send_email config | Use `template: { id: "..." }` — template is a nested object |
+| Using `seconds` in delay config (old naming) | Use `duration` (e.g. `"30 minutes"`) — `seconds` is no longer accepted |
+| Forgetting to enable the automation | Automations default to `disabled` — set `status: "enabled"` on create or update |
+| Not checking `error` in Node.js | SDK returns `{ data, error }`, does not throw — always destructure and check |