email-delivery

What this skill does

# Email Delivery Skill

Comprehensive patterns and templates for implementing robust email delivery with Resend, covering single emails, batch operations, scheduled delivery, and attachment handling.

## Use When

- Building transactional email systems (confirmations, notifications, alerts)
- Implementing batch email campaigns (up to 100 recipients per request)
- Setting up scheduled/delayed email delivery
- Handling file attachments, buffers, or URL-based attachments
- Adding reply-to, CC, and BCC functionality
- Creating email templates with variables and dynamic content
- Implementing retry logic and delivery error handling

## Core Patterns

### 1. Single Email Sending

**Transactional emails** for immediate delivery with minimal latency:

```typescript
import { Resend } from 'resend';

const resend = new Resend('your_resend_key_here');

async function sendTransactionalEmail() {
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Welcome to Example',
    html: '<h1>Welcome!</h1><p>Thank you for signing up.</p>',
  });

  if (error) {
    console.error('Failed to send email:', error);
    return null;
  }

  return data;
}
```

### 2. Batch Email Sending

**Bulk operations** for sending up to 100 emails in a single request:

```typescript
async function sendBatchEmails(recipients: Array<{email: string; name: string}>) {
  const emails = recipients.map(recipient => ({
    from: '[email protected]',
    to: recipient.email,
    subject: `Hello ${recipient.name}!`,
    html: `<p>Welcome ${recipient.name}</p>`,
  }));

  const { data, error } = await resend.batch.send(emails);

  if (error) {
    console.error('Batch send failed:', error);
    return null;
  }

  return data;
}
```

### 3. Scheduled Email Delivery

**Time-based delivery** for emails sent at specific times:

```typescript
async function scheduleEmail(scheduledAt: Date) {
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Scheduled Message',
    html: '<p>This was scheduled!</p>',
    scheduled_at: scheduledAt.toISOString(),
  });

  if (error) {
    console.error('Failed to schedule email:', error);
    return null;
  }

  return data;
}
```

### 4. Attachment Handling

**File attachments** from files, buffers, or URLs:

#### File-based Attachment

```typescript
import fs from 'fs';
import path from 'path';

async function sendWithFileAttachment(filePath: string) {
  const fileContent = fs.readFileSync(filePath);
  const fileName = path.basename(filePath);

  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Your Document',
    html: '<p>Please find attached your document.</p>',
    attachments: [
      {
        filename: fileName,
        content: fileContent,
      },
    ],
  });

  return { data, error };
}
```

#### Buffer-based Attachment

```typescript
async function sendWithBufferAttachment(buffer: Buffer, filename: string) {
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Monthly Report',
    html: '<p>Your monthly report is attached.</p>',
    attachments: [
      {
        filename: filename,
        content: buffer,
      },
    ],
  });

  return { data, error };
}
```

#### URL-based Attachment

```typescript
async function sendWithUrlAttachment(fileUrl: string) {
  const response = await fetch(fileUrl);
  const buffer = await response.arrayBuffer();

  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Download Your File',
    html: '<p>Your file is ready.</p>',
    attachments: [
      {
        filename: 'document.pdf',
        content: Buffer.from(buffer),
      },
    ],
  });

  return { data, error };
}
```

### 5. Reply-To and CC/BCC

**Message routing** with multiple recipients and reply addresses:

```typescript
async function sendWithRouting(mainRecipient: string) {
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: mainRecipient,
    reply_to: '[email protected]',
    cc: ['[email protected]'],
    bcc: ['[email protected]'],
    subject: 'Support Ticket #12345',
    html: '<p>We received your support request.</p>',
  });

  return { data, error };
}
```

## Python Patterns

### Single Email (Python)

```python
import os
from resend import Resend

client = Resend(api_key=os.environ.get("RESEND_API_KEY"))

def send_email():
    email = {
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Welcome",
        "html": "<h1>Welcome!</h1>",
    }

    response = client.emails.send(email)
    return response
```

### Batch Email (Python)

```python
def send_batch_emails(recipients):
    emails = [
        {
            "from": "[email protected]",
            "to": recipient["email"],
            "subject": f"Hello {recipient['name']}",
            "html": f"<p>Welcome {recipient['name']}</p>",
        }
        for recipient in recipients
    ]

    response = client.batch.send(emails)
    return response
```

### File Attachment (Python)

```python
def send_with_attachment(file_path):
    with open(file_path, 'rb') as f:
        file_content = f.read()

    email = {
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Your Document",
        "html": "<p>Document attached.</p>",
        "attachments": [
            {
                "filename": "document.pdf",
                "content": file_content,
            }
        ],
    }

    response = client.emails.send(email)
    return response
```

## Template Variables

### Environment Variables Required

```bash
RESEND_API_KEY=your_resend_key_here
[email protected]
```

### Email Template Variables

```typescript
interface EmailPayload {
  from: string;              // Verified sender email
  to: string | string[];     // Recipient(s)
  cc?: string[];            // Carbon copy recipients
  bcc?: string[];           // Blind carbon copy
  reply_to?: string;        // Reply-to address
  subject: string;          // Email subject
  html?: string;            // HTML content
  text?: string;            // Plain text fallback
  attachments?: Array<{
    filename: string;
    content: Buffer | string;
  }>;
  scheduled_at?: string;    // ISO 8601 datetime for scheduling
  tags?: Array<{
    name: string;
    value: string;
  }>;
}
```

## Best Practices

### Error Handling

Always implement retry logic for transient failures:

```typescript
async function sendWithRetry(emailPayload, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const { data, error } = await resend.emails.send(emailPayload);

    if (!error) return { data, success: true };

    if (error.message?.includes('rate_limit') && attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return { error, success: false };
  }
}
```

### Rate Limiting

Resend has rate limits. For batch operations over 100 emails:

```typescript
async function sendLargeBatch(emails: EmailPayload[]) {
  const batchSize = 100;
  const results = [];

  for (let i = 0; i < emails.length; i += batchSize) {
    const batch = emails.slice(i, i + batchSize);
    const { data, error } = await resend.batch.send(batch);

    if (error) {
      console.error(`Batch ${Math.floor(i / batchSize) + 1} failed:`, error);
      results.push({ success: false, error });
    } else {
      results.push({ success: true, data });
    }

    // Rate limit handling - wait between batches
    if (i + batchSize < emails.length) {
      await new Promise(resolve => setTimeout(resolve, 10