mailer

README

Mailer Module

An email sending module built on Gomail, integrated with Uber Fx for dependency injection.

Features

• Uber Fx dependency injection integration
• SMTP support with TLS
• Simple message composition API
• Configuration via Viper

Installation

go get github.com/weedbox/common-modules/mailer

Quick Start

Basic Usage

package main

import (
    "github.com/weedbox/common-modules/logger"
    "github.com/weedbox/common-modules/mailer"
    "go.uber.org/fx"
)

func main() {
    fx.New(
        logger.Module(),
        mailer.Module("mailer"),
    ).Run()
}

Sending Email

package notification

import (
    "context"

    "github.com/weedbox/common-modules/mailer"
    "go.uber.org/fx"
    "go.uber.org/zap"
)

type Params struct {
    fx.In

    Logger *zap.Logger
    Mailer *mailer.Mailer
}

type NotificationService struct {
    params Params
    logger *zap.Logger
}

func (s *NotificationService) SendWelcomeEmail(to, name string) error {
    msg := s.params.Mailer.NewMessage()

    msg.SetHeader("From", "noreply@example.com")
    msg.SetHeader("To", to)
    msg.SetHeader("Subject", "Welcome!")
    msg.SetBody("text/html", "<h1>Hello "+name+"!</h1><p>Welcome to our service.</p>")

    return s.params.Mailer.Send(msg)
}

func (s *NotificationService) SendEmailWithAttachment(to, subject, body, filePath string) error {
    msg := s.params.Mailer.NewMessage()

    msg.SetHeader("From", "noreply@example.com")
    msg.SetHeader("To", to)
    msg.SetHeader("Subject", subject)
    msg.SetBody("text/plain", body)
    msg.Attach(filePath)

    return s.params.Mailer.Send(msg)
}

Configuration

Configuration is managed via Viper. All config keys are prefixed with the module's scope:

Key	Default	Description
{scope}.host	0.0.0.0	SMTP server host
{scope}.port	25	SMTP server port
{scope}.username	""	SMTP username
{scope}.password	""	SMTP password
{scope}.tls	false	Enable TLS

TOML Configuration Example

[mailer]
host = "smtp.example.com"
port = 587
username = "user@example.com"
password = "secret"
tls = true

Environment Variables Example

export MAILER_HOST=smtp.example.com
export MAILER_PORT=587
export MAILER_USERNAME=user@example.com
export MAILER_PASSWORD=secret
export MAILER_TLS=true

API Reference

Mailer

Module(scope string) fx.Option

Creates a Mailer module and returns an Fx Option.

• scope: Module namespace, used for config key prefix and logger naming

NewMessage() *gomail.Message

Creates a new email message.

msg := mailer.NewMessage()
msg.SetHeader("From", "sender@example.com")
msg.SetHeader("To", "recipient@example.com")
msg.SetHeader("Subject", "Test Email")
msg.SetBody("text/plain", "This is a test email.")

Send(msg *gomail.Message) error

Sends an email message.

err := mailer.Send(msg)
if err != nil {
    // Handle error
}

Message Composition

Plain Text Email

msg := mailer.NewMessage()
msg.SetHeader("From", "sender@example.com")
msg.SetHeader("To", "recipient@example.com")
msg.SetHeader("Subject", "Plain Text Email")
msg.SetBody("text/plain", "This is plain text content.")

HTML Email

msg := mailer.NewMessage()
msg.SetHeader("From", "sender@example.com")
msg.SetHeader("To", "recipient@example.com")
msg.SetHeader("Subject", "HTML Email")
msg.SetBody("text/html", "<h1>Hello</h1><p>This is HTML content.</p>")

Email with Attachment

msg := mailer.NewMessage()
msg.SetHeader("From", "sender@example.com")
msg.SetHeader("To", "recipient@example.com")
msg.SetHeader("Subject", "Email with Attachment")
msg.SetBody("text/plain", "Please see the attached file.")
msg.Attach("/path/to/file.pdf")

Multiple Recipients

msg := mailer.NewMessage()
msg.SetHeader("From", "sender@example.com")
msg.SetHeader("To", "recipient1@example.com", "recipient2@example.com")
msg.SetHeader("Cc", "cc@example.com")
msg.SetHeader("Bcc", "bcc@example.com")
msg.SetHeader("Subject", "Email to Multiple Recipients")
msg.SetBody("text/plain", "Hello everyone!")

License

Apache License 2.0

Documentation

Index

• Constants
• func Module(scope string) fx.Option
• type Mailer
  • func (m *Mailer) NewMessage() *gomail.Message
  • func (m *Mailer) Send(msg *gomail.Message) error
• type Params

Constants

const (
	DefaultHost     = "0.0.0.0"
	DefaultPort     = 25
	DefaultUsername = ""
	DefaultPassword = ""
	DefaultTLS      = false
)

Functions

func Module

func Module(scope string) fx.Option

Types

type Mailer

type Mailer struct {
	// contains filtered or unexported fields
}

func (*Mailer) NewMessage

func (m *Mailer) NewMessage() *gomail.Message

func (*Mailer) Send

func (m *Mailer) Send(msg *gomail.Message) error

type Params

type Params struct {
	fx.In

	Lifecycle fx.Lifecycle
	Logger    *zap.Logger
}