mail

Documentation

Overview

Purpose: This file implements the GoMail email sending component. It provides an interface and implementation for sending rich text and HTML emails via SMTP.

Philosophy: Email sending is a core utility for user communication (verification, reset, notifications). We provide a production-ready, pure standard library implementation based on `net/smtp`. This adheres to our zero-dependency framework core while providing a clean, ergonomic API that handles all low-level SMTP formatting and handshakes.

Architecture: The mailer exposes a `Mailer` struct which is initialized with `Config`. The global `gostack.Mail` facade allows easy application-wide usage. The mail component defines a `Message` representing SMTP metadata and payload.

Choice: We chose a direct `net/smtp.SendMail` wrapper because it is fast, simple, and is part of the Go stdlib. By wrapping it, we support standard auth types and structure the headers/body automatically to avoid common issues with MIME formatting.

Implementation: - Config: holds SMTP server information. - Message: represents the details of an email to be sent. - Attachment: represents a file to be attached. - Mailer: holds config and provides Send() method. - MessageBuilder: fluent builder for constructing messages step-by-step.

Index

• type Attachment
• type Config
• type Mailer
  • func NewMailer(cfg Config) *Mailer
  • func (m *Mailer) BuildRaw(msg Message) []byte
  • func (m *Mailer) Send(msg any) error
• type Message
• type MessageBuilder
  • func NewMessage(subject string) *MessageBuilder
  • func (b *MessageBuilder) Attach(filename string, content []byte, mimeType ...string) *MessageBuilder
  • func (b *MessageBuilder) BCC(recipients ...string) *MessageBuilder
  • func (b *MessageBuilder) Build() Message
  • func (b *MessageBuilder) CC(recipients ...string) *MessageBuilder
  • func (b *MessageBuilder) HTML(body string) *MessageBuilder
  • func (b *MessageBuilder) ReplyTo(addr string) *MessageBuilder
  • func (b *MessageBuilder) Text(body string) *MessageBuilder
  • func (b *MessageBuilder) To(recipients ...string) *MessageBuilder

Types

type Attachment

type Attachment struct {
	Filename string // Name as shown to the recipient
	MIMEType string // e.g. "application/pdf"; auto-detected from Filename if empty
	Content  []byte // Raw file bytes
}

Attachment represents a file to embed in the email as a MIME attachment.

type Config

type Config struct {
	Host        string
	Port        int
	Username    string
	Password    string
	FromAddress string
	FromName    string
}

Config defines the configuration properties required to connect to an SMTP server.

type Mailer

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

Mailer handles SMTP email dispatch.

func NewMailer

func NewMailer(cfg Config) *Mailer

NewMailer creates a new Mailer instance.

func (*Mailer) BuildRaw

func (m *Mailer) BuildRaw(msg Message) []byte

BuildRaw formats the Message into a raw SMTP bytes payload with correct MIME headers. Supports multipart/alternative (text+HTML), file attachments, BCC, and Reply-To.

func (*Mailer) Send

func (m *Mailer) Send(msg any) error

Send formats and sends the given Message via SMTP.

type Message

type Message struct {
	To          []string
	CC          []string
	BCC         []string
	ReplyTo     string
	Subject     string
	Body        string // Plain-text body
	HTMLBody    string // HTML body (when non-empty, a multipart/alternative message is built)
	IsHTML      bool   // Deprecated: prefer HTMLBody; kept for backward compatibility
	Attachments []Attachment
}

Message represents an individual email message.

type MessageBuilder

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

MessageBuilder provides a fluent API for composing email messages. All methods return the builder itself, enabling chaining.

func NewMessage

func NewMessage(subject string) *MessageBuilder

NewMessage returns a fluent MessageBuilder seeded with a subject.

func (*MessageBuilder) Attach

func (b *MessageBuilder) Attach(filename string, content []byte, mimeType ...string) *MessageBuilder

Attach adds a file attachment.

func (*MessageBuilder) BCC

func (b *MessageBuilder) BCC(recipients ...string) *MessageBuilder

BCC sets the blind carbon-copy recipient list.

func (*MessageBuilder) Build

func (b *MessageBuilder) Build() Message

Build returns the fully constructed Message.

func (*MessageBuilder) CC

func (b *MessageBuilder) CC(recipients ...string) *MessageBuilder

CC sets the carbon-copy recipient list.

func (*MessageBuilder) HTML

func (b *MessageBuilder) HTML(body string) *MessageBuilder

HTML sets the HTML body content.

func (*MessageBuilder) ReplyTo

func (b *MessageBuilder) ReplyTo(addr string) *MessageBuilder

ReplyTo sets the Reply-To address.

func (*MessageBuilder) Text

func (b *MessageBuilder) Text(body string) *MessageBuilder

Text sets the plain-text body content.

func (*MessageBuilder) To

func (b *MessageBuilder) To(recipients ...string) *MessageBuilder

To sets the primary recipient list.