Email Package

The github.com/dracory/email package provides comprehensive email sending and templating utilities for Go applications. It supports SMTP sending, HTML templates, and flexible configuration.

Installation

go get github.com/dracory/email

Quick Start

Basic Email Sending

package main

import (
    "github.com/dracory/email"
)

func main() {
    // Create SMTP sender
    sender := email.NewSMTPSender(email.Config{
        Host:     "smtp.gmail.com",
        Port:     "587",
        Username: "your-email@gmail.com",
        Password: "your-password",
    })
    
    // Send email
    err := sender.Send(email.SendOptions{
        From:     "sender@example.com",
        To:       []string{"recipient@example.com"},
        Subject:  "Hello World",
        HtmlBody: "<h1>Hello!</h1><p>This is a test email.</p>",
        TextBody: "Hello!\n\nThis is a test email.",
    })
    
    if err != nil {
        panic(err)
    }
}

Email Templates

// Create HTML email template
htmlContent := `
    <h1>Welcome {{.AppName}}</h1>
    <p>Thank you for joining us!</p>
    <p>Visit our <a href="{{.WebsiteURL}}">website</a>.</p>
`

// Use default template with styling
styledEmail := email.DefaultTemplate(email.TemplateOptions{
    Title:       "Welcome!",
    Content:     htmlContent,
    AppName:     "MyApp",
    HeaderLinks: map[string]string{
        "Home":   "https://myapp.com",
        "About":  "https://myapp.com/about",
    },
})

// Send styled email
sender.Send(email.SendOptions{
    To:       []string{"user@example.com"},
    Subject:  "Welcome to MyApp!",
    HtmlBody: styledEmail,
})

Configuration

SMTP Configuration

The package supports various SMTP configurations:

// Gmail
config := email.Config{
    Host:     "smtp.gmail.com",
    Port:     "587",
    Username: "your-email@gmail.com",
    Password: "your-app-password", // Use app password for Gmail
}

// Outlook/Hotmail
config := email.Config{
    Host:     "smtp-mail.outlook.com",
    Port:     "587",
    Username: "your-email@outlook.com",
    Password: "your-password",
}

// SendGrid
config := email.Config{
    Host:     "smtp.sendgrid.net",
    Port:     "587",
    Username: "apikey",
    Password: "your-sendgrid-api-key",
}

Advanced Options

sender := email.NewSMTPSender(email.Config{
    Host:              "smtp.example.com",
    Port:              "587",
    Username:          "user@example.com",
    Password:          "password",
    TLS:               true,  // Enable TLS
    SkipTLSValidation: false, // Validate TLS certificates
})

Features

• Multiple SMTP Providers: Gmail, Outlook, SendGrid, and custom SMTP servers
• HTML & Text Support: Send both HTML and plain text versions
• Template System: Built-in email templates with styling
• Flexible Configuration: Easy configuration for different providers
• Error Handling: Comprehensive error reporting
• TLS Support: Secure email sending with TLS encryption

Migration from Base Package

If you were previously using github.com/dracory/base/email, update your imports:

// Old
import baseEmail "github.com/dracory/base/email"

// New  
import "github.com/dracory/email"

// Usage remains the same
sender := email.NewSMTPSender(email.Config{...})

Integration with Blueprint

The Blueprint framework automatically uses this email package. To configure email in your Blueprint application:

1. Set environment variables:

   MAIL_HOST=smtp.gmail.com
   MAIL_PORT=587
   MAIL_USERNAME=your-email@gmail.com
   MAIL_PASSWORD=your-password
   

2. Use the email utilities in your controllers:

   import "project/internal/emails"
   
   // Send email using Blueprint's email utilities
   err := emails.SendEmail(emails.SendOptions{
       To:      []string{"user@example.com"},
       Subject: "Welcome!",
       HtmlBody: "<h1>Welcome!</h1>",
   })
   

Error Handling

The package provides detailed error information:

err := sender.Send(options)
if err != nil {
    // Handle specific error types
    switch {
    case strings.Contains(err.Error(), "authentication failed"):
        log.Println("Invalid SMTP credentials")
    case strings.Contains(err.Error(), "connection refused"):
        log.Println("SMTP server unreachable")
    default:
        log.Printf("Email error: %v", err)
    }
}

Best Practices

1. Use App Passwords: For Gmail, use app passwords instead of your main password
2. Environment Variables: Store SMTP credentials in environment variables
3. Error Logging: Always log email sending errors for debugging
4. Template Validation: Validate HTML templates before sending
5. Rate Limiting: Respect rate limits of email providers

Examples

See the examples directory for complete working examples.