@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/send-email/references/single-email-examples.md

@@ -0,0 +1,470 @@
+# Resend Examples
+
+## Table of Contents
+
+- [Idempotency Keys](#idempotency-keys)
+- [Error Handling](#error-handling)
+- [Retry Logic](#retry-logic)
+- [Complete Examples](#complete-examples)
+
+## Idempotency Keys
+
+Use idempotency keys to prevent duplicate emails when retrying failed requests. Keys expire after 24 hours and have a max length of 256 characters.
+
+**Key format:** Use `<event-type>/<entity-id>` pattern (e.g., `welcome-email/user-123`, `order-confirmation/order-456`).
+
+**Behavior:** If same key is sent with a different payload, Resend returns a 409 error. If same key with same payload, returns the original response without resending.
+
+### Node.js
+
+The Node.js SDK has a dedicated `idempotencyKey` option:
+
+```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: 'Order Confirmation',
+    html: '<p>Your order has been confirmed.</p>',
+  },
+  {
+    idempotencyKey: `order-confirmation/${orderId}`,
+  }
+);
+```
+
+### 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": "Order Confirmation",
+    "html": "<p>Your order has been confirmed.</p>",
+}, idempotency_key=f"order-confirmation/{order_id}")
+```
+
+### Go
+
+Other SDKs use the `Idempotency-Key` header:
+
+```go
+import "github.com/resend/resend-go/v3"
+
+client := resend.NewClient(os.Getenv("RESEND_API_KEY"))
+
+params := &resend.SendEmailRequest{
+    From:    "Acme <onboarding@resend.dev>",
+    To:      []string{"delivered@resend.dev"},
+    Subject: "Order Confirmation",
+    Html:    "<p>Your order has been confirmed.</p>",
+    Headers: map[string]string{
+        "Idempotency-Key": fmt.Sprintf("order-confirmation/%s", orderID),
+    },
+}
+
+sent, err := client.Emails.Send(params)
+```
+
+### cURL
+
+```bash
+curl -X POST 'https://api.resend.com/emails' \
+  -H 'Authorization: Bearer re_xxxxxxxxx' \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: order-confirmation/12345' \
+  -d '{
+    "from": "Acme <onboarding@resend.dev>",
+    "to": ["delivered@resend.dev"],
+    "subject": "Order Confirmation",
+    "html": "<p>Your order has been confirmed.</p>"
+  }'
+```
+
+## Error Handling
+
+### Common Error Codes
+
+| Code | Description | Action |
+|------|-------------|--------|
+| 400 | Bad request (invalid params) | Fix request parameters |
+| 400 | `invalid_idempotency_key` | Key must be 1-256 characters |
+| 401 | Invalid API key | Check RESEND_API_KEY |
+| 403 | Domain not verified | Verify domain at resend.com/domains |
+| 409 | `invalid_idempotent_request` | Key already used with different payload |
+| 409 | `concurrent_idempotent_requests` | Same key request in progress, retry later |
+| 422 | Unprocessable entity | Check email format/content |
+| 429 | Rate limited | Implement backoff and retry |
+| 500 | Server error | Retry with backoff |
+
+### 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',
+  html: '<p>Hello world</p>',
+});
+
+if (error) {
+  console.error('Failed to send email:', error.message);
+
+  // Handle specific error types
+  if (error.name === 'validation_error') {
+    // Invalid parameters - don't retry
+    throw new Error(`Invalid email params: ${error.message}`);
+  }
+
+  if (error.name === 'rate_limit_exceeded') {
+    // Rate limited - retry after delay
+    console.log('Rate limited, retrying...');
+  }
+
+  return;
+}
+
+console.log('Email sent:', data.id);
+```
+
+### Python
+
+```python
+import resend
+import os
+
+resend.api_key = os.environ["RESEND_API_KEY"]
+
+try:
+    email = resend.Emails.send({
+        "from": "Acme <onboarding@resend.dev>",
+        "to": ["delivered@resend.dev"],
+        "subject": "Hello",
+        "html": "<p>Hello world</p>",
+    })
+    print(f"Email sent: {email['id']}")
+except resend.exceptions.ValidationError as e:
+    # Invalid parameters - don't retry
+    print(f"Validation error: {e}")
+except resend.exceptions.RateLimitError as e:
+    # Rate limited - retry after delay
+    print(f"Rate limited: {e}")
+except resend.exceptions.ResendError as e:
+    # Other API error
+    print(f"API error: {e}")
+```
+
+### Go
+
+```go
+import (
+    "fmt"
+    "github.com/resend/resend-go/v3"
+)
+
+client := resend.NewClient(os.Getenv("RESEND_API_KEY"))
+
+params := &resend.SendEmailRequest{
+    From:    "Acme <onboarding@resend.dev>",
+    To:      []string{"delivered@resend.dev"},
+    Subject: "Hello",
+    Html:    "<p>Hello world</p>",
+}
+
+sent, err := client.Emails.Send(params)
+if err != nil {
+    // Check error type and handle accordingly
+    fmt.Printf("Failed to send email: %v\n", err)
+    return
+}
+
+fmt.Printf("Email sent: %s\n", sent.Id)
+```
+
+## Retry Logic
+
+Implement exponential backoff for transient failures (rate limits, server errors). Don't retry 409 `invalid_idempotent_request` errors (different payload).
+
+### Node.js
+
+```typescript
+import { Resend } from 'resend';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+async function sendEmailWithRetry(
+  params: Parameters<typeof resend.emails.send>[0],
+  options: { maxRetries?: number; idempotencyKey?: string } = {}
+) {
+  const { maxRetries = 3, idempotencyKey } = options;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const { data, error } = await resend.emails.send(
+      params,
+      idempotencyKey ? { idempotencyKey } : undefined
+    );
+
+    if (!error) {
+      return data;
+    }
+
+    // Don't retry validation errors or idempotency conflicts
+    if (error.name === 'validation_error' || error.name === 'invalid_idempotent_request') {
+      throw new Error(`${error.name}: ${error.message}`);
+    }
+
+    // Last attempt failed
+    if (attempt === maxRetries) {
+      throw new Error(`Failed after ${maxRetries + 1} attempts: ${error.message}`);
+    }
+
+    // Exponential backoff: 1s, 2s, 4s...
+    const delay = Math.pow(2, attempt) * 1000;
+    console.log(`Attempt ${attempt + 1} failed, retrying in ${delay}ms...`);
+    await new Promise(resolve => setTimeout(resolve, delay));
+  }
+}
+
+// Usage
+const result = await sendEmailWithRetry(
+  {
+    from: 'Acme <onboarding@resend.dev>',
+    to: ['delivered@resend.dev'],
+    subject: 'Order Confirmation',
+    html: '<p>Your order is confirmed.</p>',
+  },
+  { idempotencyKey: `order-confirmation/${orderId}` }
+);
+```
+
+### Python
+
+```python
+import resend
+import os
+import time
+
+resend.api_key = os.environ["RESEND_API_KEY"]
+
+def send_email_with_retry(params, max_retries=3, idempotency_key=None):
+    for attempt in range(max_retries + 1):
+        try:
+            return resend.Emails.send(params, idempotency_key=idempotency_key)
+        except resend.exceptions.ValidationError:
+            # Don't retry validation errors
+            raise
+        except resend.exceptions.ResendError as e:
+            if attempt == max_retries:
+                raise Exception(f"Failed after {max_retries + 1} attempts: {e}")
+
+            # Exponential backoff: 1s, 2s, 4s...
+            delay = (2 ** attempt)
+            print(f"Attempt {attempt + 1} failed, retrying in {delay}s...")
+            time.sleep(delay)
+
+# Usage
+result = send_email_with_retry(
+    {
+        "from": "Acme <onboarding@resend.dev>",
+        "to": ["delivered@resend.dev"],
+        "subject": "Order Confirmation",
+        "html": "<p>Your order is confirmed.</p>",
+    },
+    idempotency_key=f"order-confirmation/{order_id}"
+)
+```
+
+### Go
+
+```go
+import (
+    "fmt"
+    "time"
+    "github.com/resend/resend-go/v3"
+)
+
+func sendEmailWithRetry(client *resend.Client, params *resend.SendEmailRequest, maxRetries int) (*resend.SendEmailResponse, error) {
+    var lastErr error
+
+    for attempt := 0; attempt <= maxRetries; attempt++ {
+        sent, err := client.Emails.Send(params)
+        if err == nil {
+            return sent, nil
+        }
+
+        lastErr = err
+
+        if attempt == maxRetries {
+            break
+        }
+
+        // Exponential backoff: 1s, 2s, 4s...
+        delay := time.Duration(1<<attempt) * time.Second
+        fmt.Printf("Attempt %d failed, retrying in %v...\n", attempt+1, delay)
+        time.Sleep(delay)
+    }
+
+    return nil, fmt.Errorf("failed after %d attempts: %w", maxRetries+1, lastErr)
+}
+
+// Usage
+client := resend.NewClient(os.Getenv("RESEND_API_KEY"))
+
+params := &resend.SendEmailRequest{
+    From:    "Acme <onboarding@resend.dev>",
+    To:      []string{"delivered@resend.dev"},
+    Subject: "Order Confirmation",
+    Html:    "<p>Your order is confirmed.</p>",
+    Headers: map[string]string{
+        "Idempotency-Key": fmt.Sprintf("order-confirmation/%s", orderID),
+    },
+}
+
+sent, err := sendEmailWithRetry(client, params, 3)
+```
+
+## Complete Examples
+
+### Node.js - Production-Ready Email Service
+
+```typescript
+import { Resend } from 'resend';
+import { randomUUID } from 'crypto';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+interface SendEmailOptions {
+  to: string | string[];
+  subject: string;
+  html: string;
+  from?: string;
+  replyTo?: string;
+  idempotencyKey?: string;
+  maxRetries?: number;
+}
+
+async function sendEmail(options: SendEmailOptions) {
+  const {
+    to,
+    subject,
+    html,
+    from = 'Acme <noreply@acme.com>',
+    replyTo,
+    idempotencyKey = randomUUID(),
+    maxRetries = 3,
+  } = options;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const { data, error } = await resend.emails.send(
+      {
+        from,
+        to: Array.isArray(to) ? to : [to],
+        subject,
+        html,
+        ...(replyTo && { replyTo }),
+      },
+      { idempotencyKey }
+    );
+
+    if (!error) {
+      return { success: true, id: data.id };
+    }
+
+    // Don't retry client errors or idempotency conflicts
+    if (error.name === 'validation_error' || error.name === 'not_found' || error.name === 'invalid_idempotent_request') {
+      return { success: false, error: error.message, retryable: false };
+    }
+
+    if (attempt < maxRetries) {
+      const delay = Math.pow(2, attempt) * 1000;
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+
+  return { success: false, error: 'Max retries exceeded', retryable: true };
+}
+
+// Usage
+const result = await sendEmail({
+  to: 'delivered@resend.dev',
+  subject: 'Welcome!',
+  html: '<h1>Welcome to Acme</h1>',
+  idempotencyKey: `welcome-email/${userId}`,
+});
+```
+
+### Python - Production-Ready Email Service
+
+```python
+import resend
+import os
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Optional, Union, List
+
+resend.api_key = os.environ["RESEND_API_KEY"]
+
+@dataclass
+class EmailResult:
+    success: bool
+    id: Optional[str] = None
+    error: Optional[str] = None
+    retryable: bool = False
+
+def send_email(
+    to: Union[str, List[str]],
+    subject: str,
+    html: str,
+    from_addr: str = "Acme <noreply@acme.com>",
+    reply_to: Optional[str] = None,
+    idempotency_key: Optional[str] = None,
+    max_retries: int = 3,
+) -> EmailResult:
+    idempotency_key = idempotency_key or str(uuid.uuid4())
+    recipients = [to] if isinstance(to, str) else to
+
+    params = {
+        "from": from_addr,
+        "to": recipients,
+        "subject": subject,
+        "html": html,
+    }
+    if reply_to:
+        params["reply_to"] = reply_to
+
+    for attempt in range(max_retries + 1):
+        try:
+            result = resend.Emails.send(params, idempotency_key=idempotency_key)
+            return EmailResult(success=True, id=result["id"])
+        except resend.exceptions.ValidationError as e:
+            return EmailResult(success=False, error=str(e), retryable=False)
+        except resend.exceptions.ResendError as e:
+            if attempt < max_retries:
+                time.sleep(2 ** attempt)
+            else:
+                return EmailResult(success=False, error=str(e), retryable=True)
+
+    return EmailResult(success=False, error="Max retries exceeded", retryable=True)
+
+# Usage
+result = send_email(
+    to="delivered@resend.dev",
+    subject="Welcome!",
+    html="<h1>Welcome to Acme</h1>",
+    idempotency_key=f"welcome-email/{user_id}",
+)
+```

package/skills/send-email/references/webhooks.md

@@ -0,0 +1,221 @@
+# Webhooks
+
+Receive real-time notifications when email events occur (delivered, bounced, opened, etc.).
+
+## When to Use Webhooks
+
+- Track delivery status in your database
+- Remove bounced addresses from mailing lists
+- Trigger follow-up actions when emails are opened/clicked
+- Create alerts for failures or complaints
+- Build custom analytics dashboards
+
+## Event Types
+
+### Email Events
+
+| Event | Trigger | Use Case |
+|-------|---------|----------|
+| `email.sent` | API request successful, delivery attempted | Confirm email accepted |
+| `email.delivered` | Email reached recipient's mail server | Confirm successful delivery |
+| `email.bounced` | Mail server permanently rejected (hard bounce) | Remove from list, alert user |
+| `email.complained` | Recipient marked as spam | Unsubscribe, review content |
+| `email.opened` | Recipient opened email | Track engagement |
+| `email.clicked` | Recipient clicked a link | Track engagement |
+| `email.delivery_delayed` | Temporary delivery issue (soft bounce) | Monitor, may resolve automatically |
+| `email.failed` | Send error (invalid recipient, quota, etc.) | Debug, alert |
+
+### Bounce Types
+
+| Type | Event | Action |
+|------|-------|--------|
+| **Hard bounce (Permanent)** | `email.bounced` | Remove address immediately - never retry |
+| **Soft bounce (Transient)** | `email.delivery_delayed` | Monitor - Resend retries automatically |
+| **Undetermined** | `email.bounced` | Treat as hard bounce if repeated |
+
+**Hard bounces** (`email.bounced`) are permanent failures. The address is invalid and will never accept mail. Continuing to send to hard-bounced addresses destroys your sender reputation.
+
+| Subtype | Cause |
+|---------|-------|
+| General | Recipient's email provider sent a hard bounce |
+| NoEmail | Address doesn't exist or couldn't be determined |
+
+**Soft bounces** (`email.delivery_delayed`) are temporary issues. Resend automatically retries these. If delivery ultimately fails after retries, you'll receive an `email.bounced` event.
+
+| Subtype | Cause | May Resolve If... |
+|---------|-------|-------------------|
+| General | Temporary rejection | Underlying issue clears |
+| MailboxFull | Recipient's inbox at capacity | Recipient frees space |
+| MessageTooLarge | Exceeds provider size limit | You reduce message size |
+| ContentRejected | Contains disallowed content | You modify content |
+| AttachmentRejected | Attachment type/size rejected | You modify attachment |
+
+**Undetermined bounces** occur when the bounce message doesn't contain enough information for Resend to determine the reason. Treat repeated undetermined bounces as hard bounces.
+
+### Other Events
+
+| Event | Trigger |
+|-------|---------|
+| `domain.created` / `updated` / `deleted` | Domain configuration changes |
+| `contact.created` / `updated` / `deleted` | Contact list changes (not from CSV imports) |
+
+## Setup
+
+1. **Create endpoint** - POST endpoint that returns HTTP 200
+2. **Add webhook** - In Resend dashboard (resend.com/webhooks), add your URL and select events
+3. **Verify signatures** - **REQUIRED** - See [Signature Verification](#signature-verification)
+4. **Test locally** - Use ngrok or similar for local development
+
+## Signature Verification
+
+**You MUST verify webhook signatures.** Without verification, attackers can send fake webhooks to your endpoint.
+
+### Why Verification Matters
+
+- Webhooks are unauthenticated HTTP POST requests
+- Anyone who knows your endpoint URL can send fake events
+- Verification ensures the webhook genuinely came from Resend
+- Unique signatures prevent replay attacks
+
+### Required Headers
+
+Every webhook includes these headers for verification:
+
+| Header | Purpose |
+|--------|---------|
+| `svix-id` | Unique message identifier |
+| `svix-timestamp` | Unix timestamp when sent |
+| `svix-signature` | Cryptographic signature |
+
+### Get Your Webhook Secret
+
+Find your signing secret in the Resend dashboard:
+1. Go to resend.com/webhooks
+2. Click on your webhook
+3. Copy the signing secret (starts with `whsec_`)
+
+Store it securely as `RESEND_WEBHOOK_SECRET` environment variable.
+
+### Using Resend SDK (Recommended)
+
+Example using Next.js:
+
+```typescript
+import { Resend } from 'resend';
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db'; // Your database client (Prisma, Drizzle, etc.)
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function POST(req: NextRequest) {
+  try {
+    // CRITICAL: Use raw body, not parsed JSON
+    const payload = await req.text();
+
+    // Throws an error if the webhook is invalid
+    // Otherwise, returns the parsed payload object
+    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,
+    });
+
+    // Handle the verified event
+    switch (event.type) {
+      case 'email.delivered':
+        // update database with the email delivery status
+        break;
+
+      case 'email.bounced':
+        // Hard bounce - remove from mailing list immediately
+        break;
+
+      case 'email.complained':
+        // Spam complaint - unsubscribe and flag
+        break;
+
+      default:
+        // handle other events
+        return new Response('OK', { status: 200, body: 'Event skipped' });
+    }
+
+    return new NextResponse('OK', { status: 200 });
+  } catch (error) {
+    console.error('Webhook verification failed:', error);
+    return new NextResponse('Invalid signature', { status: 400 });
+  }
+}
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Not verifying signatures | **Always verify** - attackers can send fake webhooks |
+| Using parsed JSON body | Use raw request body - JSON parsing breaks signature |
+| Using `express.json()` middleware | Use `express.raw()` for webhook routes |
+| Hardcoding webhook secret | Store in environment variable |
+| Returning non-200 status for valid webhooks | Return 200 OK to acknowledge receipt |
+
+## Retry Schedule
+
+If your endpoint doesn't return HTTP 200, Resend retries with exponential backoff:
+
+| Attempt | Delay After Failure |
+|---------|---------------------|
+| 1 | Immediate |
+| 2 | 5 seconds |
+| 3 | 5 minutes |
+| 4 | 30 minutes |
+| 5 | 2 hours |
+| 6 | 5 hours |
+| 7 | 10 hours |
+
+Example: A webhook that fails 3 times before succeeding will be delivered ~35 minutes after the first attempt.
+
+**Tip:** Always return 200 quickly, then process asynchronously if needed. You can manually replay failed webhooks from the dashboard.
+
+## IP Allowlist
+
+If your firewall requires allowlisting, webhooks come from:
+
+```
+44.228.126.217
+50.112.21.217
+52.24.126.164
+54.148.139.208
+```
+
+IPv6: `2600:1f24:64:8000::/52`
+
+## Local Development
+
+Use tunneling tools to test webhooks locally:
+
+```bash
+# ngrok
+ngrok http 3000
+
+# use the port that your server is running on (e.g. 3000)
+# Then use the ngrok URL in Resend dashboard
+# https://abc123.ngrok.io/webhooks/resend
+```
+
+## Event Payload Example
+
+```json
+{
+  "type": "email.delivered",
+  "created_at": "2024-01-15T12:00:00.000Z",
+  "data": {
+    "email_id": "ae2014de-c168-4c61-8267-70d2662a1ce1",
+    "from": "Acme <noreply@acme.com>",
+    "to": ["delivered@resend.dev"],
+    "subject": "Welcome to Acme"
+  }
+}
+```