Skip to Content
DocumentationPackage LibraryMailer

Mailer

The mailer package provides a unified email sending interface with support for SMTP, SendGrid, and Brevo (formerly Sendinblue) drivers. It includes HTML template rendering, attachments, and batch sending.

Import

import "github.com/gofastadev/gofasta/pkg/mailer"

Key Types

Mailer

type Mailer interface {
    Send(ctx context.Context, msg Message) error
    SendBatch(ctx context.Context, msgs []Message) error
    Close() error
}

Message

type Message struct {
    From        Address       `json:"from"`
    To          []Address     `json:"to"`
    CC          []Address     `json:"cc,omitempty"`
    BCC         []Address     `json:"bcc,omitempty"`
    ReplyTo     *Address      `json:"reply_to,omitempty"`
    Subject     string        `json:"subject"`
    Body        string        `json:"body"`
    HTMLBody    string        `json:"html_body,omitempty"`
    Attachments []Attachment  `json:"attachments,omitempty"`
    Headers     map[string]string `json:"headers,omitempty"`
}

Address

type Address struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

Attachment

type Attachment struct {
    Filename    string `json:"filename"`
    ContentType string `json:"content_type"`
    Content     []byte `json:"-"`
}

EmailConfig

The email configuration uses koanf struct tags and is part of the root AppConfig. Environment variables use the GOFASTA_ prefix (e.g., GOFASTA_EMAIL_PROVIDER). Email templates use Go’s html/template for rendering.

type EmailConfig struct {
    Provider    string         `koanf:"provider"`
    FromName    string         `koanf:"from_name"`
    FromAddress string         `koanf:"from_address"`
    SMTP        SMTPConfig     `koanf:"smtp"`
    SendGrid    SendGridConfig `koanf:"sendgrid"`
    Brevo       BrevoConfig    `koanf:"brevo"`
}
 
type SMTPConfig struct {
    Host     string `koanf:"host"`
    Port     int    `koanf:"port"`
    Username string `koanf:"username"`
    Password string `koanf:"password"`
    UseTLS   bool   `koanf:"use_tls"`
}
 
type SendGridConfig struct {
    APIKey string `koanf:"api_key"`
}
 
type BrevoConfig struct {
    APIKey string `koanf:"api_key"`
}

Key Functions

FunctionSignatureDescription
NewMailerfunc NewMailer(cfg MailerConfig) (Mailer, error)Creates a mailer using the configured driver
NewSMTPMailerfunc NewSMTPMailer(cfg MailerConfig) (Mailer, error)Creates an SMTP mailer
NewSendGridMailerfunc NewSendGridMailer(cfg MailerConfig) (Mailer, error)Creates a SendGrid mailer
NewBrevoMailerfunc NewBrevoMailer(cfg MailerConfig) (Mailer, error)Creates a Brevo mailer
RenderTemplatefunc RenderTemplate(templatePath string, data interface{}) (string, error)Renders an HTML email template with the given data

Usage

Sending a Simple Email

m, err := mailer.NewMailer(mailer.MailerConfig{
    Driver:    "smtp",
    Host:      "smtp.gmail.com",
    Port:      587,
    Username:  "user@gmail.com",
    Password:  "app-password",
    FromName:  "My App",
    FromEmail: "noreply@myapp.com",
})
if err != nil {
    log.Fatalf("failed to create mailer: %v", err)
}
defer m.Close()
 
err = m.Send(ctx, mailer.Message{
    To:      []mailer.Address{{Name: "Jane", Email: "jane@example.com"}},
    Subject: "Welcome to My App",
    Body:    "Thanks for signing up!",
})

Sending with HTML Template

Create a template file at templates/welcome.html:

<h1>Welcome, {{.Name}}!</h1>
<p>Your account has been created successfully.</p>
<a href="{{.VerifyURL}}">Verify your email</a>

Render and send:

htmlBody, err := mailer.RenderTemplate("templates/welcome.html", map[string]string{
    "Name":      "Jane",
    "VerifyURL": "https://myapp.com/verify?token=abc123",
})
if err != nil {
    return err
}
 
err = m.Send(ctx, mailer.Message{
    To:       []mailer.Address{{Name: "Jane", Email: "jane@example.com"}},
    Subject:  "Welcome to My App",
    HTMLBody: htmlBody,
})

Sending with Attachments

pdfContent, _ := os.ReadFile("invoice.pdf")
 
err = m.Send(ctx, mailer.Message{
    To:      []mailer.Address{{Email: "customer@example.com"}},
    Subject: "Your Invoice",
    Body:    "Please find your invoice attached.",
    Attachments: []mailer.Attachment{
        {
            Filename:    "invoice.pdf",
            ContentType: "application/pdf",
            Content:     pdfContent,
        },
    },
})

Configuration via config.yaml

email:
  provider: sendgrid   # "smtp", "sendgrid", or "brevo"
  from_name: "My App"
  from_address: "noreply@myapp.com"
  smtp:
    host: smtp.gmail.com
    port: 587
    username: "user@gmail.com"
    password: "app-password"
    use_tls: true
  sendgrid:
    api_key: "SG.xxxxx"
  brevo:
    api_key: "xkeysib-xxxxx"

Environment variable overrides use the GOFASTA_ prefix:

export GOFASTA_EMAIL_PROVIDER=sendgrid
export GOFASTA_EMAIL_SENDGRID_API_KEY=SG.xxxxx
export GOFASTA_EMAIL_FROM_ADDRESS=noreply@myapp.com
  • Config — Mailer configuration loading
  • Queue — Queue email sending for async delivery
  • Notifications — Higher-level notification dispatch
  • Slack — Outbound chat sibling
  • WhatsApp — Outbound WhatsApp sibling
  • Push Notifications — Outbound mobile push sibling
  • i18n — Translate email template content per locale
Last updated on
StorageSlack