Go Bolo Emails Plugin

A powerful email management plugin for the Go Bolo framework that provides template-based email delivery with support for SMTP, message queue integration, and a REST API for managing emails and templates.

Features

• Template-Based Emails: Create reusable email templates with Handlebars syntax
• SMTP Integration: Send emails via SMTP with TLS support
• Message Queue Support: Queue emails for delivery using RabbitMQ (via msgbroker plugin)
• CSS Inlining: Automatic CSS inlining for better email client compatibility using Premailer
• REST API: Full CRUD operations for emails and templates
• Database Storage: Persist email records and templates in MySQL/SQLite
• Retry Mechanism: Automatic retry logic for failed deliveries
• Multiple Recipients: Support for To, CC, BCC, and Reply-To fields

Installation

go get github.com/go-bolo/emails

Requirements

• Go 1.20+
• Go Bolo framework v1.1.0+
• Database (MySQL or SQLite)
• SMTP server credentials (for email delivery)
• (Optional) RabbitMQ via msgbroker plugin for queued delivery

Configuration

Set the following environment variables:

# SMTP Configuration
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-username
SMTP_PASSWORD=your-password
SMTP_FROM=noreply@example.com
SMTP_REPLY_TO=support@example.com

# Enable email delivery (leave empty to disable)
ENABLE_EMAIL_DELIVERY=true

# Environment
GO_ENV=production

Usage

Initialize the Plugin

package main

import (
    "github.com/go-bolo/bolo"
    "github.com/go-bolo/emails"
)

func main() {
    app := bolo.Init(&bolo.AppOptions{})

    // Create and register the email plugin
    app.RegisterPlugin(emails.NewPlugin(&emails.PluginCfg{}))

    err = app.Bootstrap()

    // app is ready to be used like:
    err := app.StartHTTPServer()
    if err != nil {
        logrus.WithFields(logrus.Fields{
            "error": fmt.Sprintf("%+v\n", err),
        }).Error("error on StartHTTPServer")
    }
}

Register Custom Email Types

Define email types with default templates and variables:

emailPlugin.AddEmailTemplate("welcome-email", &emails.EmailType{
    Label:          "Welcome Email",
    DefaultSubject: "Welcome to {{appName}}!",
    DefaultHTML:    "<h1>Hello {{userName}}!</h1><p>Welcome to our platform.</p>",
    DefaultText:    "Hello {{userName}}! Welcome to our platform.",
    TemplateVariables: map[string]*emails.TemplateVariable{
        "userName": {
            Example:     "John Doe",
            Description: "The name of the user",
        },
        "appName": {
            Example:     "MyApp",
            Description: "The application name",
        },
    },
})

Send an Email with Template

email, err := emails.NewEmailWithTemplate(&emails.EmailOpts{
    To:           "user@example.com",
    TemplateName: "welcome-email",
    Variables: emails.TemplateVariables{
        "userName": "John Doe",
        "appName":  "MyApp",
    },
})
if err != nil {
    log.Fatal(err)
}

// Send immediately
err = email.Send()

// Or queue for background delivery
err = email.QueueToSend()

Send Email Asynchronously

emails.SendEmailAsync(&emails.EmailOpts{
    To:           "user@example.com",
    TemplateName: "welcome-email",
    Variables: emails.TemplateVariables{
        "userName": "John Doe",
    },
})

Send Email Without Template

email := &emails.Email{
    To:      "user@example.com",
    From:    "noreply@example.com",
    Subject: "Custom Email",
    HTML:    "<p>This is a custom email</p>",
    Text:    "This is a custom email",
}

err := email.Send()

API Endpoints

The plugin automatically registers the following REST API endpoints:

Email Management

• GET /api/email - List all emails (with pagination and search)
• GET /api/email/:id - Get a specific email
• POST /api/email - Create a new email record
• PUT /api/email/:id - Update an email
• DELETE /api/email/:id - Delete an email
• GET /api/email/count - Count emails

Email Template Management

• GET /api/email-template - List all email templates
• GET /api/email-template/:id - Get a specific template
• POST /api/email-template - Create a new template
• PUT /api/email-template/:id - Update a template
• DELETE /api/email-template/:id - Delete a template
• GET /api/email-template-types - Get all registered email types

Query Parameters

• q - Search term (searches subject and text)
• order / sort - Column to sort by
• sortDirection - Sort direction (asc or desc)
• limit - Number of results per page
• offset - Pagination offset

Template Syntax

Templates use Handlebars syntax:

Subject: Welcome
{{userName}}! HTML:
<h1>Hello {{userName}}!</h1>
<p>Thank you for joining {{appName}}.</p>
<p>Your account email is: {{userEmail}}</p>

Message Queue Integration

When the msgbroker plugin is available, emails are automatically queued to the notification-email-delivery queue instead of being sent immediately. This provides:

• Async Processing: Non-blocking email delivery
• Retry Logic: Automatic retry on failure (up to 3 attempts)
• Scalability: Distribute email sending across multiple workers

Permissions

The plugin uses the following permissions (integrate with your ACL system):

• create_email - Create email records
• find_email - View emails
• update_email - Update email records
• delete_email - Delete emails
• create_email-template - Create templates
• update_email-template - Update templates
• delete_email-template - Delete templates

Development

Running Tests

go test -v ./...

Project Structure

.
├── Email.go                    # Core email sending logic
├── EmailModel.go              # Email database model
├── EmailController.go         # Email REST API controller
├── EmailTemplateModel.go      # Template database model
├── EmailTemplateController.go # Template REST API controller
├── EmailType.go               # Email type definitions
├── Plugin.go                  # Plugin initialization
├── emails.go                  # Helper functions
├── email-templates.go         # Template utilities
├── migrations/                # Database migrations
│   └── 00001_init.go
└── *_test.go                  # Test files

Dependencies

• go-bolo/bolo - Core framework
• go-bolo/msgbroker - Message queue integration
• labstack/echo - HTTP router
• gorm.io/gorm - ORM
• gopkg.in/mail.v2 - SMTP client
• aymerick/raymond - Handlebars templates
• vanng822/go-premailer - CSS inlining

License

This project is part of the Go Bolo framework.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• Create an issue on GitHub
• Check the Go Bolo documentation