email

Documentation

Overview

Package email is part of the GoFastr framework. See https://github.com/DonaldMurillo/gofastr for documentation.

Package email provides a pluggable email system with SMTP sending, development logging, and template rendering capabilities.

Index

• Variables
• func LoadFromDir(dir string) (map[string]Template, error)
• func LoadFromFS(fsys fs.FS) (map[string]Template, error)
• type Attachment
• type Email
  • func Execute(tmpl Template, data map[string]any) (Email, error)
• type LogSender
  • func NewLogSender(w ...io.Writer) *LogSender
  • func (l *LogSender) Send(_ context.Context, email Email) error
• type SMTPConfig
  • func (c SMTPConfig) Validate() error
• type SMTPSender
  • func NewSMTPSender(config SMTPConfig) *SMTPSender
  • func (s *SMTPSender) Send(ctx context.Context, email Email) error
• type Sender
• type Template

Variables

var ErrSendFailed = errors.New("email: send failed")

ErrSendFailed is returned when an email fails to send.

Functions

func LoadFromDir

func LoadFromDir(dir string) (map[string]Template, error)

LoadFromDir loads email templates from a directory. It expects files with .txt and .html extensions, paired by name. For example, "welcome.txt" and "welcome.html" become a Template named "welcome". Subject lines are extracted from the first line of .txt files if it starts with "Subject: ", or from .html files if no .txt is present. Alternatively, a .subject file with the same base name can provide the subject.

func LoadFromFS

func LoadFromFS(fsys fs.FS) (map[string]Template, error)

LoadFromFS loads email templates from an fs.FS.

Types

type Attachment

type Attachment struct {
	Filename    string
	Content     []byte
	ContentType string
}

Attachment represents an email attachment with its content.

type Email

type Email struct {
	To          []string
	CC          []string
	BCC         []string
	From        string
	Subject     string
	TextBody    string
	HTMLBody    string
	Attachments []Attachment
	Headers     map[string]string
}

Email represents an email message.

func Execute

func Execute(tmpl Template, data map[string]any) (Email, error)

Execute fills the template with the provided data and returns a complete Email. The From and To fields must be set by the caller after execution.

type LogSender

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

LogSender is a development email sender that logs email details to an io.Writer instead of actually sending them.

func NewLogSender

func NewLogSender(w ...io.Writer) *LogSender

NewLogSender creates a new LogSender that writes to the provided writer. If no writer is provided, it defaults to os.Stdout.

func (*LogSender) Send

func (l *LogSender) Send(_ context.Context, email Email) error

Send implements the Sender interface by logging the email details.

type SMTPConfig

type SMTPConfig struct {
	Host     string
	Port     int
	Username string
	Password string
	// UseTLS dials with implicit TLS (e.g. port 465). When false, the
	// sender opportunistically attempts STARTTLS on the cleartext
	// connection.
	UseTLS bool
	// AllowCleartext, when true, permits the message to be transmitted
	// without any transport encryption (no implicit TLS and STARTTLS
	// either unavailable or not negotiated). It defaults to false so the
	// sender fails CLOSED: if neither implicit TLS nor STARTTLS could be
	// established, Send returns an error instead of leaking the message
	// and recipient list in cleartext (defends against STARTTLS
	// stripping by an on-path attacker). Set true only for trusted
	// local relays where plaintext is acceptable.
	AllowCleartext bool

	// DialTimeout bounds the TCP (and, for UseTLS, the TLS handshake)
	// connect. Zero uses defaultSMTPDialTimeout (10s). The request
	// context's deadline still applies and wins when it is sooner.
	// The same budget is also set as the connection's I/O deadline, so
	// a server that accepts the dial and then stalls mid-exchange
	// (never sends the greeting, wedges after MAIL) cannot hang the
	// worker either.
	DialTimeout time.Duration
}

SMTPConfig holds the configuration for an SMTP sender.

func (SMTPConfig) Validate

func (c SMTPConfig) Validate() error

Validate checks that the SMTPConfig has required fields.

type SMTPSender

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

SMTPSender sends emails via SMTP.

func NewSMTPSender

func NewSMTPSender(config SMTPConfig) *SMTPSender

NewSMTPSender creates a new SMTPSender with the given configuration.

func (*SMTPSender) Send

func (s *SMTPSender) Send(ctx context.Context, email Email) error

Send implements the Sender interface using SMTP.

type Sender

type Sender interface {
	Send(ctx context.Context, email Email) error
}

Sender is the interface for sending emails.

type Template

type Template struct {
	Subject  string
	TextBody string
	HTMLBody string
}

Template represents an email template with subject, text, and HTML bodies. Fields may contain Go template directives like {{.Name}}.