smtp

Documentation

Overview

Package smtp provides an SMTP-based implementation of the email.EmailSender interface.

This package enables sending HTML emails through any SMTP server with support for STARTTLS, direct TLS, and plain connections. It validates configuration and email parameters to prevent runtime failures.

Basic usage:

import (
	"context"
	"github.com/dmitrymomot/foundation/core/email"
	"github.com/dmitrymomot/foundation/integration/email/smtp"
)

cfg := smtp.Config{
	Host:         "smtp.gmail.com",
	Port:         587,
	Username:     "your-email@gmail.com",
	Password:     "your-app-password",
	TLSMode:      "starttls",
	SenderEmail:  "noreply@example.com",
	SupportEmail: "support@example.com",
}

sender, err := smtp.New(cfg)
if err != nil {
	// Handle configuration error
}

params := email.SendEmailParams{
	SendTo:   "user@example.com",
	Subject:  "Welcome!",
	BodyHTML: "<h1>Welcome to our service</h1>",
	Tag:      "welcome",
}

err = sender.SendEmail(context.Background(), params)
if err != nil {
	// Handle sending error
}

Configuration

The Config struct defines all required SMTP settings:

• Host: SMTP server hostname (required)
• Port: SMTP server port, typically 587 for STARTTLS or 465 for TLS (required)
• Username: SMTP authentication username (required)
• Password: SMTP authentication password (required)
• TLSMode: Connection security mode - "starttls", "tls", or "plain" (required)
• SenderEmail: From address for outgoing emails (required, validated)
• SupportEmail: Reply-To address for email responses (required, validated)

All fields are validated during client creation to catch configuration errors early.

TLS Modes

Three TLS modes are supported:

• "starttls": Start with plain connection, upgrade to TLS (recommended, port 587)
• "tls": Direct TLS connection (port 465)
• "plain": No encryption (development only, port 25)

Dependency Injection

Use MustNewClient for dependency injection patterns:

type Services struct {
	EmailSender email.EmailSender
}

func NewServices(cfg smtp.Config) *Services {
	return &Services{
		EmailSender: smtp.MustNewClient(cfg), // Panics on invalid config
	}
}

Index

• func MustNewClient(cfg Config) email.EmailSender
• func New(cfg Config) (email.EmailSender, error)
• type Client
  • func (c *Client) SendEmail(ctx context.Context, params email.SendEmailParams) error
• type Config

Functions

func MustNewClient

func MustNewClient(cfg Config) email.EmailSender

MustNewClient creates an SMTP client that panics on invalid config. Follows framework pattern of failing fast during initialization rather than allowing broken services to start.

func New

func New(cfg Config) (email.EmailSender, error)

New creates an SMTP-backed email sender. All configuration fields are required for runtime operation to ensure explicit configuration and avoid silent failures in production.

Types

type Client

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

Client implements the EmailSender interface using standard SMTP protocol. Supports multiple TLS modes (STARTTLS, TLS, plain) and is thread-safe for concurrent use.

func (*Client) SendEmail

func (c *Client) SendEmail(ctx context.Context, params email.SendEmailParams) error

SendEmail implements EmailSender using SMTP protocol. Supports STARTTLS, TLS, and plain text connections based on configuration. The context is used for timeout control during the SMTP transaction.

type Config

type Config struct {
	Host         string `env:"SMTP_HOST,required"`
	Port         int    `env:"SMTP_PORT" envDefault:"587"`
	Username     string `env:"SMTP_USERNAME,required"`
	Password     string `env:"SMTP_PASSWORD,required"`
	TLSMode      string `env:"SMTP_TLS_MODE" envDefault:"starttls"` // starttls, tls, or plain
	SenderEmail  string `env:"SENDER_EMAIL,required"`
	SupportEmail string `env:"SUPPORT_EMAIL,required"`
}

Config holds SMTP server configuration. All fields are required for runtime operation to ensure explicit configuration and avoid silent failures in production.