> ## Documentation Index > Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt > Use this file to discover all available pages before exploring further. # email Operation > Send transactional and marketing emails via Cloudflare Email, Resend, or SMTP with template rendering, batch processing, and attachment support. From simple messages to complex batch campaigns with personalized templates and file attachments. ## Basic Usage ```yaml theme={null} operations: - name: send-welcome operation: email config: provider: cloudflare from: welcome@example.com to: ${input.email} subject: Welcome to Our Platform! html: |

Welcome {{input.name}}!

We're excited to have you on board.

``` ## Configuration ```yaml theme={null} config: provider: string # cloudflare, resend, smtp from: string # Sender email address to: string | string[] # Recipient(s) subject: string # Email subject body: string # Plain text body html: string # HTML body cc: string | string[] # CC recipients (optional) bcc: string | string[] # BCC recipients (optional) replyTo: string # Reply-to address (optional) attachments: array # File attachments (optional) headers: object # Custom headers (optional) tags: string[] # Email tags (optional) metadata: object # Custom metadata (optional) ``` ## Email Providers ### Cloudflare Email (Recommended) Zero-configuration email sending via Cloudflare Email Routing: ```yaml theme={null} operations: - name: send operation: email config: provider: cloudflare from: noreply@example.com fromName: Your App to: ${input.email} subject: Your Receipt html:

Thank you for your purchase!

``` **wrangler.toml** configuration: ```toml theme={null} [[send_email]] name = "EMAIL" destination_address_list = "allowed-recipients" # Optional allowlist [env.production] [[env.production.send_email]] name = "EMAIL" destination_address_list = "production-recipients" ``` **Features**: * No API key required * Automatic DKIM signing * 100,000 emails/day free tier * Edge-native performance * Instant delivery ### Resend Developer-friendly email API with great deliverability: ```yaml theme={null} operations: - name: send operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} from: team@example.com to: ${input.email} subject: Welcome! html:

Welcome to our platform

``` **Environment Variables**: ```bash theme={null} RESEND_API_KEY=re_123456789 ``` **Features**: * Simple REST API * Email analytics dashboard * 100 emails/day free tier * Webhook support * React Email integration ### SMTP Generic SMTP for any mail server: ```yaml theme={null} operations: - name: send operation: email config: provider: smtp host: smtp.gmail.com port: 587 secure: true auth: user: ${env.SMTP_USER} pass: ${env.SMTP_PASS} from: alerts@example.com to: ${input.email} subject: Alert Notification html:

Alert: {{input.message}}

``` **Supported Services**: * Gmail * SendGrid * Mailgun * Amazon SES * Custom SMTP servers ## Email Templates ### Inline HTML Simple emails with inline HTML: ```yaml theme={null} operations: - name: send-confirmation operation: email config: provider: cloudflare from: orders@example.com to: ${input.customer_email} subject: Order #${input.order_id} Confirmed html: |

Order Confirmed!

Hi {{input.customer_name}},

Your order #{{input.order_id}} has been confirmed.

Total: ${{input.total}}

View Order
``` ### Template Variables Use template expressions for dynamic content: ```yaml theme={null} operations: - name: send-notification operation: email config: provider: cloudflare from: notifications@example.com to: ${input.email} subject: ${input.notification_type} - Action Required html: |

Hello {{input.name}}!

{{input.message}}

Generated at {{new Date().toLocaleString()}}

``` ### Liquid Templates (Advanced) For complex templates, store them in KV with Liquid syntax: ```yaml theme={null} operations: # Step 1: Fetch template from KV - name: get-template operation: storage config: type: kv action: get key: email-templates/welcome # Step 2: Render template with Liquid - name: render operation: code config: script: scripts/render-liquid-template input: template: ${get-template.output.value} name: ${input.name} activationUrl: ${input.activation_url} appName: 'Your App' # Step 3: Send rendered email - name: send operation: email config: provider: cloudflare from: welcome@example.com to: ${input.email} subject: Welcome to Your App! html: ${render.output.html} ``` ```typescript theme={null} // scripts/render-liquid-template.ts import type { AgentExecutionContext } from '@ensemble-edge/conductor' export default async function renderLiquidTemplate(context: AgentExecutionContext) { const { template, name, activationUrl, appName } = context.input const Liquid = require('liquidjs') const engine = new Liquid() const rendered = await engine.parseAndRender(template, { name, activationUrl, appName }) return { html: rendered } } ``` **Template in KV**: ```liquid theme={null}

Welcome {{ name | capitalize }}!

Click below to activate your account:

Activate Account

Best regards,
The {{ appName }} Team

``` ## Email Attachments ### Single Attachment ```yaml theme={null} operations: - name: send-invoice operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} from: billing@example.com to: ${input.customer_email} subject: Your Invoice html:

Please find your invoice attached.

attachments: - filename: invoice.pdf content: ${generate-pdf.output.content} contentType: application/pdf encoding: base64 ``` ### Multiple Attachments ```yaml theme={null} operations: - name: send-report operation: email config: provider: cloudflare from: reports@example.com to: ${input.email} subject: Monthly Report html:

Your monthly report is attached.

attachments: - filename: report.pdf content: ${generate-pdf.output} contentType: application/pdf encoding: base64 - filename: data.csv content: ${export-csv.output} contentType: text/csv encoding: utf8 - filename: summary.txt content: "Total Sales: $${input.total_sales}" contentType: text/plain ``` ### Attachment from Storage ```yaml theme={null} operations: # Step 1: Fetch file from R2 - name: get-file operation: storage config: type: r2 action: get key: invoices/${input.invoice_id}.pdf # Step 2: Email with attachment - name: send operation: email config: provider: cloudflare from: billing@example.com to: ${input.email} subject: Invoice #${input.invoice_id} html:

Invoice attached

attachments: - filename: invoice-${input.invoice_id}.pdf content: ${get-file.output.content} contentType: application/pdf ``` ## Batch Sending Send personalized emails to multiple recipients: ```yaml theme={null} operations: - name: send-newsletter operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} from: newsletter@example.com batch: recipients: - email: alice@example.com name: Alice lastPurchase: Laptop - email: bob@example.com name: Bob lastPurchase: Phone - email: charlie@example.com name: Charlie lastPurchase: Tablet subject: Your Weekly Newsletter html: |

Hi {{ name }}!

Based on your recent purchase of {{ lastPurchase }}, we have recommendations for you.

rateLimit: 10 # Emails per second ``` **Output**: ```yaml theme={null} { sent: 3, failed: 0, messageIds: ["msg-1", "msg-2", "msg-3"], errors: [] } ``` ## CC and BCC ```yaml theme={null} operations: - name: send-update operation: email config: provider: cloudflare from: updates@example.com to: customer@example.com cc: - manager@example.com - team@example.com bcc: archive@example.com subject: Project Update html:

Project status: In Progress

``` ## Reply-To Set a different reply address: ```yaml theme={null} operations: - name: send-support operation: email config: provider: cloudflare from: noreply@example.com replyTo: support@example.com to: ${input.email} subject: Support Ticket #${input.ticket_id} html:

Your support ticket has been created. Reply to this email for updates.

``` ## Custom Headers Add tracking and custom headers: ```yaml theme={null} operations: - name: send-campaign operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} from: marketing@example.com to: ${input.email} subject: Special Offer! html:

Limited time offer!

headers: X-Campaign-ID: campaign-2024-q1 X-Customer-Segment: premium List-Unsubscribe: X-Priority: 1 ``` ## Tags and Metadata Organize and track emails: ```yaml theme={null} operations: - name: send-order-confirmation operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} from: orders@example.com to: ${input.email} subject: Order Confirmation html:

Your order has been confirmed!

tags: - transactional - order-confirmation - ${input.customer_segment} metadata: orderId: ${input.order_id} customerId: ${input.customer_id} orderValue: ${input.total} ``` ## Common Patterns ### Transactional Email ```yaml theme={null} ensemble: send-order-confirmation inputs: order_id: string customer_email: string customer_name: string items: array total: number operations: - name: send operation: email config: provider: cloudflare from: orders@shop.com to: ${input.customer_email} subject: Order #${input.order_id} Confirmed html: |

Thank you, {{input.customer_name}}!

Your order #{{input.order_id}} has been confirmed.

Order Details:

Total: ${{input.total}}

outputs: messageId: ${send.output.messageId} success: ${send.output.success} ``` ### Welcome Email Workflow ```yaml theme={null} ensemble: welcome-new-user inputs: email: string name: string userId: string operations: # Generate activation token - name: generate-token operation: code config: script: scripts/generate-activation-token # Store token in KV - name: store-token operation: storage config: type: kv action: put key: activation:${input.userId} value: ${generate-token.output.token} ttl: 86400 # 24 hours ``` ```typescript theme={null} // scripts/generate-activation-token.ts import type { AgentExecutionContext } from '@ensemble-edge/conductor' export default function generateActivationToken(context: AgentExecutionContext) { const crypto = require('crypto') const token = crypto.randomBytes(32).toString('hex') return { token, expiresAt: Date.now() + 86400000 // 24 hours } } ``` ```yaml theme={null} # Send welcome email - name: send operation: email config: provider: cloudflare from: welcome@example.com to: ${input.email} subject: Welcome to Our Platform! html: |

Welcome {{input.name}}!

Click below to activate your account:

Activate Account

This link expires in 24 hours.

outputs: sent: true activationToken: ${generate-token.output.token} ``` ### Password Reset Email ```yaml theme={null} ensemble: password-reset inputs: email: string userId: string operations: # Generate reset token - name: generate-token operation: code config: script: scripts/generate-reset-token # Store token - name: store-token operation: storage config: type: kv action: put key: reset:${input.userId} value: ${generate-token.output.token} ttl: 3600 ``` ```typescript theme={null} // scripts/generate-reset-token.ts import type { AgentExecutionContext } from '@ensemble-edge/conductor' export default function generateResetToken(context: AgentExecutionContext) { const crypto = require('crypto') return { token: crypto.randomBytes(32).toString('hex'), expiresAt: Date.now() + 3600000 // 1 hour } } ``` ```yaml theme={null} # Send reset email - name: send operation: email config: provider: cloudflare from: security@example.com to: ${input.email} subject: Password Reset Request html: |

Reset Your Password

Click below to reset your password:

Reset Password

This link expires in 1 hour.

If you didn't request this, ignore this email.

outputs: sent: true resetToken: ${generate-token.output.token} ``` ### Email with PDF Invoice ```yaml theme={null} ensemble: send-invoice inputs: customer_email: string customer_name: string invoice_number: string items: array total: number operations: # Generate PDF - name: generate-pdf operation: pdf config: html: |

Invoice #{{input.invoice_number}}

Bill To: {{input.customer_name}}

{{input.items.map(item => ` `).join('')}}
ItemQuantityPriceTotal
${item.name} ${item.quantity} $${item.price} $${item.quantity * item.price}

Total: ${{input.total}}

format: A4 # Email PDF - name: send operation: email config: provider: cloudflare from: billing@example.com to: ${input.customer_email} subject: Invoice #${input.invoice_number} html: |

Hi {{input.customer_name}},

Thank you for your business! Your invoice is attached.

Invoice #: {{input.invoice_number}}

Amount: ${{input.total}}

attachments: - filename: invoice-${input.invoice_number}.pdf content: ${generate-pdf.output} contentType: application/pdf encoding: base64 outputs: sent: true messageId: ${send.output.messageId} ``` ### Data Export Email ```yaml theme={null} ensemble: export-and-email inputs: admin_email: string export_type: string operations: # Export data from KV - name: export operation: storage config: type: kv action: export prefix: users: format: csv exportOptions: headers: true fields: [id, email, name, created_at] # Convert to base64 - name: encode operation: code config: script: scripts/encode-export-data input: data: ${export.output.data} ``` ```typescript theme={null} // scripts/encode-export-data.ts import type { AgentExecutionContext } from '@ensemble-edge/conductor' export default function encodeExportData(context: AgentExecutionContext) { const { data } = context.input return { content: btoa(data), filename: `export-${Date.now()}.csv` } } ``` ```yaml theme={null} # Email export - name: send operation: email config: provider: cloudflare from: reports@example.com to: ${input.admin_email} subject: Data Export - ${input.export_type} html: |

Data Export Report

Your requested {{input.export_type}} export is attached.

attachments: - filename: ${encode.output.filename} content: ${encode.output.content} contentType: text/csv encoding: base64 outputs: sent: true recordCount: ${export.output.count} ``` ### Newsletter Campaign ```yaml theme={null} ensemble: send-newsletter inputs: subject: string content: string operations: # Fetch subscriber list - name: get-subscribers operation: storage config: type: d1 query: | SELECT email, name, preferences FROM subscribers WHERE active = true AND newsletter_opt_in = true # Send batch emails - name: send-campaign operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} from: newsletter@example.com batch: recipients: ${get-subscribers.output.results} subject: ${input.subject} html: ${input.content} rateLimit: 5 # 5 emails/second headers: List-Unsubscribe: outputs: sent: ${send-campaign.output.sent} failed: ${send-campaign.output.failed} totalSubscribers: ${get-subscribers.output.results.length} ``` ## Error Handling ### Retry on Failure ```yaml theme={null} operations: - name: send operation: email config: provider: cloudflare from: alerts@example.com to: ${input.email} subject: Important Alert html:

{{input.message}}

retry: maxAttempts: 3 backoff: exponential # 1s, 2s, 4s delays ``` ### Fallback Provider ```yaml theme={null} operations: # Try primary provider - name: send-primary operation: email config: provider: cloudflare from: alerts@example.com to: ${input.email} subject: Alert html:

{{input.message}}

# Fallback to SMTP if primary fails - name: send-fallback condition: ${send-primary.failed} operation: email config: provider: smtp host: smtp.gmail.com port: 587 secure: true auth: user: ${env.SMTP_USER} pass: ${env.SMTP_PASS} from: backup@example.com to: ${input.email} subject: Alert html:

{{input.message}}

outputs: sent: ${send-primary.success || send-fallback.success} provider: ${send-primary.success ? 'cloudflare' : 'smtp'} ``` ### Validate Email Address ```yaml theme={null} operations: # Validate email - name: validate operation: code config: script: scripts/validate-email input: email: ${input.email} # Send if valid - name: send condition: ${validate.output.valid} operation: email config: provider: cloudflare from: info@example.com to: ${input.email} subject: Welcome html:

Welcome!

``` ```typescript theme={null} // scripts/validate-email.ts import type { AgentExecutionContext } from '@ensemble-edge/conductor' export default function validateEmail(context: AgentExecutionContext) { const { email } = context.input const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/ if (!emailRegex.test(email)) { throw new Error('Invalid email address') } return { valid: true } } ``` ```yaml theme={null} ### Handle Batch Errors ``` ```yaml theme={null} operations: - name: send-batch operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} from: newsletter@example.com batch: recipients: ${input.recipients} subject: Newsletter html: ${input.content} # Log errors - name: log-errors condition: ${send-batch.output.failed > 0} operation: storage config: type: kv action: put key: email-errors:${Date.now()} value: ${send-batch.output.errors} outputs: sent: ${send-batch.output.sent} failed: ${send-batch.output.failed} errors: ${send-batch.output.errors} ``` ## Testing ### Test with TestConductor ```typescript theme={null} import { describe, it, expect } from 'vitest'; import { TestConductor } from '@ensemble/conductor/testing'; describe('send-welcome-email', () => { it('should send welcome email', async () => { const conductor = await TestConductor.create({ projectPath: './conductor', mocks: { email: { 'send-welcome': { success: true, messageId: 'msg-123', provider: 'cloudflare' } } } }); const result = await conductor.executeAgent('send-welcome-email', { email: 'test@example.com', name: 'Test User' }); expect(result).toBeSuccessful(); expect(result.output.messageId).toBe('msg-123'); }); it('should handle invalid email', async () => { const conductor = await TestConductor.create({ projectPath: './conductor' }); const result = await conductor.executeAgent('send-welcome-email', { email: 'invalid-email', name: 'Test User' }); expect(result).toBeFailed(); expect(result.error).toContain('Invalid email'); }); }); ``` ### Mock Email Provider ```typescript theme={null} const conductor = await TestConductor.create({ mocks: { email: { '*': { // Mock all email operations success: true, messageId: 'mock-msg-id', timestamp: new Date().toISOString() } } } }); ``` ## Best Practices **1. Use Plain Text Fallback** ```yaml theme={null} # Good: Include plain text version operations: - name: send operation: email config: provider: cloudflare html:

Welcome!

Thanks for signing up.

body: | Welcome! Thanks for signing up. # Bad: HTML only operations: - name: send operation: email config: provider: cloudflare html:

Welcome!

Thanks for signing up.

``` **2. Validate Recipients** ```yaml theme={null} # Good: Validate before sending operations: - name: validate operation: code config: script: scripts/validate-email-simple input: email: ${input.email} - name: send operation: email # Bad: No validation operations: - name: send operation: email config: to: ${input.email} # Could be invalid ``` ```typescript theme={null} // scripts/validate-email-simple.ts import type { AgentExecutionContext } from '@ensemble-edge/conductor' export default function validateEmailSimple(context: AgentExecutionContext) { const { email } = context.input if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) { throw new Error('Invalid email') } return { valid: true } } ``` ```yaml theme={null} **3. Set Reply-To for No-Reply Emails** ``` ```yaml theme={null} # Good: Set reply-to operations: - name: send operation: email config: from: noreply@example.com replyTo: support@example.com subject: Notification # Bad: No reply-to with noreply operations: - name: send operation: email config: from: noreply@example.com subject: Notification ``` **4. Rate Limit Batch Sending** ```yaml theme={null} # Good: Set rate limit operations: - name: send-batch operation: email config: batch: recipients: ${input.recipients} rateLimit: 10 # 10 emails/second # Bad: No rate limiting operations: - name: send-batch operation: email config: batch: recipients: ${input.recipients} ``` **5. Include Unsubscribe Link** ```yaml theme={null} # Good: Include unsubscribe operations: - name: send operation: email config: html: |

Newsletter content...

Unsubscribe

headers: List-Unsubscribe: # Bad: No unsubscribe link operations: - name: send operation: email config: html:

Newsletter content...

``` **6. Use Tags for Organization** ```yaml theme={null} # Good: Tag emails operations: - name: send operation: email config: tags: - transactional - order-confirmation metadata: orderId: ${input.order_id} # Bad: No tags or metadata operations: - name: send operation: email ``` **7. Store API Keys in Environment** ```yaml theme={null} # Good: Use environment variables operations: - name: send operation: email config: provider: resend apiKey: ${env.RESEND_API_KEY} # Bad: Hardcoded API key operations: - name: send operation: email config: provider: resend apiKey: re_123456789 # Never do this! ``` **8. Handle Attachments Safely** ```yaml theme={null} # Good: Validate attachment size operations: - name: validate-size operation: code config: script: scripts/validate-attachment-size input: attachmentLength: ${input.attachment.length} - name: send operation: email config: attachments: - filename: ${input.filename} content: ${input.attachment} # Bad: No size validation operations: - name: send operation: email config: attachments: - content: ${input.attachment} ``` ```typescript theme={null} // scripts/validate-attachment-size.ts import type { AgentExecutionContext } from '@ensemble-edge/conductor' export default function validateAttachmentSize(context: AgentExecutionContext) { const { attachmentLength } = context.input const maxSize = 10 * 1024 * 1024 // 10MB if (attachmentLength > maxSize) { throw new Error('Attachment too large') } return { valid: true } } ``` ```yaml theme={null} ## Common Pitfalls ### Pitfall: Missing From Address ``` ```yaml theme={null} # Bad: No from address - name: send operation: email config: to: user@example.com subject: Hello # Good: Include from - name: send operation: email config: from: info@example.com to: user@example.com subject: Hello ``` ### Pitfall: HTML Without Plain Text ```yaml theme={null} # Bad: HTML only - name: send operation: email config: html:

Content

# Good: Include both - name: send operation: email config: html:

Content

body: Content ``` ### Pitfall: No Error Handling ```yaml theme={null} # Bad: No retry or fallback - name: send operation: email config: provider: cloudflare # Good: Retry and fallback - name: send-primary operation: email config: provider: cloudflare retry: maxAttempts: 3 - name: send-fallback condition: ${send-primary.failed} operation: email config: provider: smtp ``` ### Pitfall: Batch Without Rate Limiting ```yaml theme={null} # Bad: No rate limit - name: send-batch operation: email config: batch: recipients: ${input.recipients} # Could hit rate limits # Good: Set rate limit - name: send-batch operation: email config: batch: recipients: ${input.recipients} rateLimit: 10 ``` ## Next Steps Send SMS messages Generate PDF documents Store email templates Test email workflows