vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/resend/references/sending/overview.md

@@ -0,0 +1,209 @@
+# Sending Emails with Resend
+
+## Overview
+
+Resend provides two endpoints for sending emails:
+
+| Approach | Endpoint | Use Case |
+|----------|----------|----------|
+| **Single** | `POST /emails` | Individual transactional emails, emails with attachments, scheduled sends |
+| **Batch** | `POST /emails/batch` | Multiple distinct emails in one request (max 100), bulk notifications |
+
+**Choose batch when:**
+- Sending 2+ distinct emails at once
+- Reducing API calls is important (by default, rate limit is 2 requests per second)
+- No attachments or scheduling needed
+
+**Choose single when:**
+- Sending one email
+- Email needs attachments
+- Email needs to be scheduled
+- Different recipients need different timing
+
+## Quick Start
+
+1. **Detect project language** from config files (package.json, requirements.txt, go.mod, etc.)
+2. **Install SDK** (preferred) or use cURL — See [../installation.md](../installation.md)
+3. **Choose single or batch** based on the decision matrix above
+4. **Implement best practices** — Idempotency keys, error handling, retries. See [best-practices.md](best-practices.md)
+
+## Single Email
+
+**Endpoint:** `POST /emails` (prefer SDK over cURL)
+
+### Required Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `from` | string | Sender address. Format: `"Name <email@domain.com>"` |
+| `to` | string[] | Recipient addresses (max 50) |
+| `subject` | string | Email subject line |
+| `html` or `text` | string | Email body content |
+
+### Optional Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cc` | string[] | CC recipients |
+| `bcc` | string[] | BCC recipients |
+| `reply_to`* | string[] | Reply-to addresses |
+| `scheduled_at`* | string | Schedule send time (ISO 8601) |
+| `attachments` | array | File attachments (max 40MB total) |
+| `tags` | array | Key/value pairs for tracking (see [Tags](#tags)) |
+| `headers` | object | Custom headers |
+| `topic_id`* | string | Scope email to a topic — if the recipient contact has opted out of this topic, the email is silently skipped |
+
+*Parameter naming varies by SDK (e.g., `replyTo` in Node.js, `reply_to` in Python).
+
+See [single-email-examples.md](single-email-examples.md) for full SDK implementations with error handling and retry logic.
+
+## Batch Email
+
+**Endpoint:** `POST /emails/batch` (prefer SDK over cURL)
+
+### Limitations
+
+- **No attachments** — Use single sends for emails with attachments
+- **No scheduling** — Use single sends for scheduled emails
+- **Atomic** — If one email fails validation, the entire batch fails
+- **Max 100 emails** per request
+- **Max 50 recipients** per individual email in the batch
+
+### Pre-validation
+
+Since the entire batch fails on any validation error, validate all emails before sending:
+- Check required fields (from, to, subject, html/text)
+- Validate email formats
+- Ensure batch size <= 100
+
+See [batch-email-examples.md](batch-email-examples.md) for full SDK implementations with validation, chunking, and retry logic.
+
+## Large Batches (100+ Emails)
+
+For sends larger than 100 emails, chunk into multiple batch requests:
+
+1. **Split into chunks** of 100 emails each
+2. **Use unique idempotency keys** per chunk: `<batch-prefix>/chunk-<index>`
+3. **Send chunks in parallel** for better throughput
+4. **Track results** per chunk to handle partial failures
+
+See [batch-email-examples.md](batch-email-examples.md) for complete chunking implementations.
+
+## Deliverability
+
+Follow these practices to maximize inbox placement.
+
+For more help with deliverability, install the email-best-practices skill with `npx skills add resend/email-best-practices`.
+
+### Required
+
+| Practice | Why |
+|----------|-----|
+| **Valid SPF, DKIM, DMARC record** | Authenticate the email and prevent spoofing |
+| **Links match sending domain** | If sending from `@acme.com`, link to `https://acme.com` — mismatched domains trigger spam filters |
+| **Include plain text version** | Use both `html` and `text` parameters for accessibility and deliverability |
+| **Avoid "no-reply" addresses** | Use real addresses (e.g., `support@`) — improves trust signals |
+| **Keep body under 102KB** | Gmail clips larger messages |
+
+### Recommended
+
+| Practice | Why |
+|----------|-----|
+| **Use subdomains** | Send transactional from `notifications.acme.com`, marketing from `mail.acme.com` — protects reputation |
+| **Disable tracking for transactional** | Open/click tracking can trigger spam filters for password resets, receipts, etc. |
+
+## Tracking (Opens & Clicks)
+
+Tracking is configured at the **domain level** in the Resend dashboard, not per-email.
+
+| Setting | How it works | Recommendation |
+|---------|--------------|----------------|
+| **Open tracking** | Inserts 1x1 transparent pixel | Disable for transactional emails |
+| **Click tracking** | Rewrites links through redirect | Disable for sensitive emails |
+
+Configure via dashboard: Domain → Configuration → Click/Open Tracking.
+
+To track different email types separately (e.g., tracking on for marketing, off for transactional), use **separate subdomains**.
+
+## Tags
+
+Tags are key/value pairs that help you track and filter emails.
+
+```typescript
+tags: [
+  { name: 'user_id', value: 'usr_123' },
+  { name: 'email_type', value: 'welcome' },
+]
+```
+
+**Constraints:** Tag names and values can only contain ASCII letters, numbers, underscores, or dashes. Max 256 characters each.
+
+## Templates
+
+Use pre-built templates instead of sending HTML with each request:
+
+```typescript
+const { data, error } = await resend.emails.send({
+  from: 'Acme <hello@acme.com>',
+  to: ['delivered@resend.dev'],
+  subject: 'Welcome!',
+  template: {
+    id: 'tmpl_abc123',       // or alias: 'welcome-email'
+    variables: {
+      USER_NAME: 'John',     // Case-sensitive! Must match template exactly.
+    }
+  }
+});
+```
+
+Cannot combine `template` with `html`, `text`, or `react` — mutually exclusive. See [../templates.md](../templates.md) for full template management.
+
+## Testing
+
+**Avoid testing with fake addresses at real email providers** — they bounce and destroy sender reputation.
+
+| Method | Address | Result |
+|--------|---------|--------|
+| **Delivered** | `delivered@resend.dev` | Simulates successful delivery |
+| **Bounced** | `bounced@resend.dev` | Simulates hard bounce |
+| **Complained** | `complained@resend.dev` | Simulates spam complaint |
+| **Your own email** | Your actual address | Real delivery test |
+
+## Domain Warm-up
+
+New domains must gradually increase sending volume to establish reputation.
+
+**New domain schedule:**
+
+| Day | Messages per day |
+|-----|-----------------|
+| 1 | Up to 150 |
+| 2 | Up to 250 |
+| 3 | Up to 400 |
+| 4 | Up to 700 |
+| 5 | Up to 1,000 |
+| 6 | Up to 1,500 |
+| 7 | Up to 2,000 |
+
+**Existing domain schedule:**
+
+| Day | Messages per day |
+|-----|-----------------|
+| 1 | Up to 1,000 |
+| 2 | Up to 2,500 |
+| 3–4 | Up to 5,000 |
+| 5–6 | Up to 7,500 |
+| 7 | Up to 10,000 |
+
+Monitor: bounce rate < 4%, spam complaint rate < 0.08%.
+
+## Suppression List
+
+Resend automatically manages a suppression list. Addresses are added when emails hard bounce or recipients mark as spam. Resend won't attempt delivery to suppressed addresses — the `email.suppressed` webhook event fires instead. Manage in Dashboard → Suppressions.
+
+## Notes
+
+- The `from` address must use a verified domain
+- If the sending address cannot receive replies, set the `reply_to` parameter
+- Node.js SDK supports `react` parameter for React Email components
+- Resend returns `{ error, data }` — data is `{ id: "email-id" }` on success (single) or array of IDs (batch)

package/dist/global-skills/resend/references/sending/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}",
+)
+```