Skip to content

armgit / posta

Public Imported from GitHub
0

Self-hosted email delivery platform that enables applications to send emails via HTTP APIs while handling SMTP delivery, templates, storage, security, and analytics. Fully self-hostable alternative to services like SendGrid or Mailgun.

19.4 KB
Raw Blame
// Copyright (c) 2026 Jonas Kaninda.
//
// This file is part of Posta.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later

package email

import (
	"crypto/rand"
	"crypto/tls"
	"encoding/base64"
	"encoding/hex"
	"errors"
	"fmt"
	"mime"
	"mime/quotedprintable"
	"net"
	"net/mail"
	"net/smtp"
	"net/textproto"
	"slices"
	"strings"
	"time"
	"unicode/utf8"

	"github.com/google/uuid"
	"github.com/goposta/posta/internal/models"
	"github.com/goposta/posta/internal/netguard"
)

// SendError carries structured information about an SMTP failure so callers can
// distinguish a permanent recipient rejection (5xx at RCPT TO) from a transient
// error worth retrying. Error() preserves the original human-readable string.
type SendError struct {
	Stage     string // "RCPT TO", "MAIL FROM", "DATA", ...
	Recipient string // bare recipient address, set for RCPT TO failures
	Code      int    // SMTP reply code (e.g. 550); 0 when not an SMTP reply
	Msg       string // server reply text, incl. enhanced status code (5.1.1 ...)
	Err       error
}

// Permanent reports whether the failure is a permanent (5xx) SMTP rejection.
func (e *SendError) Permanent() bool { return e.Code >= 500 && e.Code < 600 }

func (e *SendError) Error() string { return e.Err.Error() }
func (e *SendError) Unwrap() error { return e.Err }

// smtpReply extracts the SMTP reply code and message from an error returned by
// the net/smtp client. It returns (0, "") when err does not wrap a
// *textproto.Error (e.g. a connection-level failure).
func smtpReply(err error) (int, string) {
	var t *textproto.Error
	if errors.As(err, &t) {
		return t.Code, t.Msg
	}
	return 0, ""
}

type SMTPSender struct{}

// workspaceNetwork decides which addresses a workspace's own SMTP servers may
// reach. Private ones are allowed unless the operator says otherwise, since a
// relay on the same host or network is a common setup.
var workspaceNetwork = netguard.Policy{AllowPrivate: true}

// SetWorkspaceSMTPNetwork sets the policy for workspace SMTP servers. Called
// once at startup, before any mail is sent.
func SetWorkspaceSMTPNetwork(p netguard.Policy) {
	workspaceNetwork = p
}

// dialerFor returns the dialer for a server: guarded for one a workspace
// member configured, plain for the operator's system server and for
// platform servers, which admins configure.
func dialerFor(server *models.SMTPServer) *net.Dialer {
	if server.WorkspaceID != nil && !server.IsSystem {
		return workspaceNetwork.Dialer(0)
	}
	return &net.Dialer{}
}

// dialSMTP connects in plain text and starts an SMTP session.
func dialSMTP(d *net.Dialer, addr, host string) (*smtp.Client, error) {
	conn, err := d.Dial("tcp", addr)
	if err != nil {
		return nil, err
	}
	client, err := smtp.NewClient(conn, host)
	if err != nil {
		_ = conn.Close()
		return nil, err
	}
	return client, nil
}

// DescribeSMTPError turns a connection or SMTP failure into a message fit to
// show a workspace member. A reply from the SMTP server, such as a refused
// login, is kept; a network error is reduced to what went wrong, without the
// addresses and ports that would map the server's network.
func DescribeSMTPError(err error) string {
	if err == nil {
		return ""
	}
	stage := err.Error()
	if i := strings.Index(stage, ":"); i > 0 {
		stage = stage[:i]
	} else {
		stage = "SMTP connection failed"
	}
	var reply *textproto.Error
	if errors.As(err, &reply) {
		return fmt.Sprintf("%s: %d %s", stage, reply.Code, reply.Msg)
	}
	return stage + ": " + netguard.Describe(err)
}

func NewSMTPSender() *SMTPSender {
	return &SMTPSender{}
}

// TestConnection verifies that a connection to the SMTP server can be
// established and, when credentials are provided, that authentication succeeds.
func (s *SMTPSender) TestConnection(server *models.SMTPServer) error {
	addr := fmt.Sprintf("%s:%d", server.Host, server.Port)
	tlsConfig := &tls.Config{ServerName: server.Host}
	dialer := dialerFor(server)

	var client *smtp.Client
	var err error

	switch server.Encryption {
	case models.EncryptionSSL:
		conn, dialErr := tls.DialWithDialer(dialer, "tcp", addr, tlsConfig)
		if dialErr != nil {
			return fmt.Errorf("SSL dial failed: %w", dialErr)
		}
		defer func() { _ = conn.Close() }()
		client, err = smtp.NewClient(conn, server.Host)
		if err != nil {
			return fmt.Errorf("SMTP client creation failed: %w", err)
		}

	case models.EncryptionSTARTTLS:
		client, err = dialSMTP(dialer, addr, server.Host)
		if err != nil {
			return fmt.Errorf("SMTP dial failed: %w", err)
		}
		if err = client.StartTLS(tlsConfig); err != nil {
			_ = client.Close()
			return fmt.Errorf("STARTTLS failed: %w", err)
		}

	default: // none
		client, err = dialSMTP(dialer, addr, server.Host)
		if err != nil {
			return fmt.Errorf("SMTP dial failed: %w", err)
		}
	}
	defer func() { _ = client.Close() }()

	if server.Username != "" {
		if err := client.Auth(newAuth(server.Host, server.Username, server.Password)); err != nil {
			return fmt.Errorf("SMTP auth failed: %w", err)
		}
	}
	return client.Quit()
}

// autoAuth uses PLAIN when the server offers it, otherwise LOGIN (Exchange Online).
type autoAuth struct {
	plain            smtp.Auth
	host, user, pass string
	login            bool
}

func newAuth(host, username, password string) smtp.Auth {
	return &autoAuth{plain: smtp.PlainAuth("", username, password, host), host: host, user: username, pass: password}
}

func (a *autoAuth) Start(server *smtp.ServerInfo) (string, []byte, error) {
	if !offers(server.Auth, "LOGIN") || offers(server.Auth, "PLAIN") {
		return a.plain.Start(server)
	}
	if !server.TLS && server.Name != "localhost" && server.Name != "127.0.0.1" && server.Name != "::1" {
		return "", nil, errors.New("unencrypted connection")
	}
	if server.Name != a.host {
		return "", nil, errors.New("wrong host name")
	}
	a.login = true
	return "LOGIN", nil, nil
}

func (a *autoAuth) Next(fromServer []byte, more bool) ([]byte, error) {
	if !a.login {
		return a.plain.Next(fromServer, more)
	}
	if !more {
		return nil, nil
	}
	switch strings.ToLower(strings.TrimSpace(string(fromServer))) {
	case "username:":
		return []byte(a.user), nil
	case "password:":
		return []byte(a.pass), nil
	}
	return nil, fmt.Errorf("unexpected LOGIN challenge %q", fromServer)
}

func offers(mechanisms []string, name string) bool {
	return slices.ContainsFunc(mechanisms, func(m string) bool { return strings.EqualFold(m, name) })
}

func (s *SMTPSender) Send(server *models.SMTPServer, from string, to []string, subject, htmlBody, textBody string, attachments []models.Attachment, headers map[string]string, listUnsubscribeURL, listUnsubscribeMailto string, listUnsubscribePost bool) error {
	addr := fmt.Sprintf("%s:%d", server.Host, server.Port)

	var auth smtp.Auth
	if server.Username != "" {
		auth = newAuth(server.Host, server.Username, server.Password)
	}

	msg := buildMessage(from, to, subject, htmlBody, textBody, attachments, headers, listUnsubscribeURL, listUnsubscribeMailto, listUnsubscribePost)

	// Extract bare email for SMTP envelope (MAIL FROM), keep full format for headers
	envelopeFrom := envelopeAddress(from)

	switch server.Encryption {
	case models.EncryptionSSL:
		return sendWithImplicitTLS(dialerFor(server), addr, auth, server.Host, envelopeFrom, to, msg)
	case models.EncryptionSTARTTLS:
		return sendWithSTARTTLS(dialerFor(server), addr, auth, server.Host, envelopeFrom, to, msg)
	default:
		return sendPlain(dialerFor(server), addr, auth, server.Host, envelopeFrom, to, msg)
	}
}

// envelopeAddress extracts the bare email from an RFC 5322 address like
// "Display Name <[email protected]>", returning just "[email protected]".
// If parsing fails, it returns the input unchanged.
func envelopeAddress(from string) string {
	addr, err := mail.ParseAddress(from)
	if err != nil {
		return from
	}
	return addr.Address
}

func sendWithImplicitTLS(dialer *net.Dialer, addr string, auth smtp.Auth, host string, from string, to []string, msg []byte) error {
	tlsConfig := &tls.Config{ServerName: host}

	conn, err := tls.DialWithDialer(dialer, "tcp", addr, tlsConfig)
	if err != nil {
		return fmt.Errorf("SSL dial failed: %w", err)
	}

	client, err := smtp.NewClient(conn, host)
	if err != nil {
		return fmt.Errorf("SMTP client creation failed: %w", err)
	}
	defer func() { _ = client.Close() }()

	return sendViaClient(client, auth, from, to, msg)
}

func sendWithSTARTTLS(dialer *net.Dialer, addr string, auth smtp.Auth, host string, from string, to []string, msg []byte) error {
	client, err := dialSMTP(dialer, addr, host)
	if err != nil {
		return fmt.Errorf("SMTP dial failed: %w", err)
	}
	defer func() { _ = client.Close() }()

	tlsConfig := &tls.Config{ServerName: host}
	if err := client.StartTLS(tlsConfig); err != nil {
		return fmt.Errorf("STARTTLS failed: %w", err)
	}

	return sendViaClient(client, auth, from, to, msg)
}

func sendPlain(dialer *net.Dialer, addr string, auth smtp.Auth, host string, from string, to []string, msg []byte) error {
	client, err := dialSMTP(dialer, addr, host)
	if err != nil {
		return fmt.Errorf("SMTP dial failed, host: %s, error: %w", host, err)
	}
	defer func() { _ = client.Close() }()

	return sendViaClient(client, auth, from, to, msg)
}

func sendViaClient(client *smtp.Client, auth smtp.Auth, from string, to []string, msg []byte) error {
	if auth != nil {
		if err := client.Auth(auth); err != nil {
			return fmt.Errorf("SMTP auth failed: %w", err)
		}
	}

	if err := client.Mail(from); err != nil {
		return wrapSendError("MAIL FROM", from, fmt.Errorf("SMTP MAIL FROM failed: %w", err))
	}
	for _, addr := range to {
		rcpt := envelopeAddress(addr)
		if err := client.Rcpt(rcpt); err != nil {
			return wrapSendError("RCPT TO", rcpt, fmt.Errorf("SMTP RCPT TO failed: %w", err))
		}
	}

	w, err := client.Data()
	if err != nil {
		return wrapSendError("DATA", "", fmt.Errorf("SMTP DATA failed: %w", err))
	}
	if _, err := w.Write(msg); err != nil {
		return fmt.Errorf("SMTP write failed: %w", err)
	}
	if err := w.Close(); err != nil {
		return wrapSendError("DATA", "", fmt.Errorf("SMTP close failed: %w", err))
	}

	return client.Quit()
}

// wrapSendError turns a stage failure into a *SendError carrying the SMTP reply
// code and recipient, while preserving the original error string.
func wrapSendError(stage, recipient string, err error) error {
	code, msg := smtpReply(err)
	return &SendError{Stage: stage, Recipient: recipient, Code: code, Msg: msg, Err: err}
}

const (
	contentTypeTextPlain = "text/plain"
	contentTypeTextHTML  = "text/html"
)

// writeTextPart writes a text body part. Non-ASCII bodies are quoted-printable
// encoded: with no Content-Transfer-Encoding the part defaults to 7bit, so raw
// UTF-8 would be a lie the next hop is free to mangle.
func writeTextPart(b *strings.Builder, mediaType, body string) {
	fmt.Fprintf(b, "Content-Type: %s; charset=\"UTF-8\"\r\n", mediaType)
	if isASCII(body) {
		b.WriteString("\r\n")
		b.WriteString(body)
		return
	}
	b.WriteString("Content-Transfer-Encoding: quoted-printable\r\n\r\n")
	w := quotedprintable.NewWriter(b)
	_, _ = w.Write([]byte(body))
	_ = w.Close()
}

func isASCII(s string) bool {
	for i := 0; i < len(s); i++ {
		if s[i] > 127 {
			return false
		}
	}
	return true
}

// encodeHeader encodes s for an unstructured header such as Subject, folding
// its encoded-words onto separate lines. Plain text containing "=?" is encoded
// too, or a reader would decode what merely looks like an encoded-word.
func encodeHeader(s string) string {
	if mime.BEncoding.Encode("UTF-8", s) == s && !strings.Contains(s, "=?") {
		return foldPlain(s)
	}
	return strings.Join(encodeWords(s), "\r\n ")
}

// encodeWords encodes s as RFC 2047 encoded-words. RFC 2047 ignores the
// whitespace between encoded-words, but some relays keep it when they
// re-encode the header, so encoded-words break only at spaces; a break inside
// a word would reach the reader as a stray space.
func encodeWords(s string) []string {
	// 39 bytes encode to 52 base64 characters, so even the first line, after
	// "Subject: ", stays within the 76 characters RFC 2047 allows a line that
	// carries encoded-words.
	const limit = 39
	chunks := []string{""}
	for i, w := range strings.Split(s, " ") {
		if i > 0 {
			w = " " + w
		}
		if n := len(chunks) - 1; chunks[n] != "" && len(chunks[n])+len(w) > limit {
			chunks = append(chunks, "")
		}
		for _, r := range w {
			if n := len(chunks) - 1; len(chunks[n])+utf8.RuneLen(r) > limit {
				chunks = append(chunks, "")
			}
			chunks[len(chunks)-1] += string(r)
		}
	}
	for i, c := range chunks {
		chunks[i] = "=?UTF-8?b?" + base64.StdEncoding.EncodeToString([]byte(c)) + "?="
	}
	return chunks
}

// encodeFrom encodes a non-ASCII sender name, folded between encoded-words.
func encodeFrom(from string) string {
	addr, err := mail.ParseAddress(from)
	if err != nil || isASCII(addr.Name) {
		return from
	}
	return strings.Join(encodeWords(addr.Name), "\r\n ") + " <" + addr.Address + ">"
}

// foldPlain folds plain text at spaces so that, after "Subject: ", each line
// stays within the 78 characters RFC 5322 §2.1.1 recommends.
func foldPlain(s string) string {
	var b strings.Builder
	n := len("Subject: ")
	for i, w := range strings.Split(s, " ") {
		if i > 0 {
			if w != "" && n+1+len(w) > 78 {
				b.WriteString("\r\n")
				n = 0
			}
			b.WriteByte(' ')
			n++
		}
		b.WriteString(w)
		n += len(w)
	}
	return b.String()
}

// hasHeader reports whether the caller-supplied headers already include key
// (header names are case-insensitive per RFC 5322).
func hasHeader(headers map[string]string, key string) bool {
	for k := range headers {
		if strings.EqualFold(k, key) {
			return true
		}
	}
	return false
}

// newBoundary returns a random MIME boundary. A fixed boundary shared by every
// message would collide with quoted or nested content that happens to contain
// the same string, and makes all Posta mail trivially fingerprintable. The
// token stays short enough that the Content-Type header line fits in 76
// characters even with the boundary quoted.
func newBoundary() string {
	var token [12]byte
	if _, err := rand.Read(token[:]); err != nil {
		// crypto/rand failing is extraordinary; a UUID keeps the boundary unique.
		return "posta-" + uuid.NewString()
	}
	return "posta-" + hex.EncodeToString(token[:])
}

func buildMessage(from string, to []string, subject, htmlBody, textBody string, attachments []models.Attachment, headers map[string]string, listUnsubscribeURL, listUnsubscribeMailto string, listUnsubscribePost bool) []byte {
	var b strings.Builder

	fmt.Fprintf(&b, "From: %s\r\n", encodeFrom(from))
	fmt.Fprintf(&b, "To: %s\r\n", strings.Join(to, ", "))
	fmt.Fprintf(&b, "Subject: %s\r\n", encodeHeader(subject))

	// RFC 5322 requires Date and recommends Message-ID; relays are free to
	// forward a message without adding them, so emit both unless the caller
	// already supplied one through custom headers.
	if !hasHeader(headers, "Date") {
		fmt.Fprintf(&b, "Date: %s\r\n", time.Now().Format(time.RFC1123Z))
	}
	if !hasHeader(headers, "Message-ID") {
		domain := "posta.local"
		if addr, err := mail.ParseAddress(from); err == nil {
			if i := strings.LastIndex(addr.Address, "@"); i >= 0 && i+1 < len(addr.Address) {
				domain = addr.Address[i+1:]
			}
		}
		fmt.Fprintf(&b, "Message-ID: <%s@%s>\r\n", uuid.NewString(), domain)
	}

	b.WriteString("MIME-Version: 1.0\r\n")

	// RFC 2369 / 8058 List-Unsubscribe. Emit mailto first, then the https URL.
	var luParts []string
	if listUnsubscribeMailto != "" {
		luParts = append(luParts, "<"+listUnsubscribeMailto+">")
	}
	if listUnsubscribeURL != "" {
		luParts = append(luParts, "<"+listUnsubscribeURL+">")
	}
	if len(luParts) > 0 {
		fmt.Fprintf(&b, "List-Unsubscribe: %s\r\n", strings.Join(luParts, ", "))
		// RFC 8058 one-click applies to the https POST target only.
		if listUnsubscribePost && listUnsubscribeURL != "" {
			b.WriteString("List-Unsubscribe-Post: List-Unsubscribe=One-Click\r\n")
		}
	}

	// Write custom headers (already filtered for safety)
	for key, value := range headers {
		fmt.Fprintf(&b, "%s: %s\r\n", key, value)
	}

	hasAttachments := len(attachments) > 0

	if hasAttachments {
		mixedBoundary := newBoundary()
		altBoundary := newBoundary()

		fmt.Fprintf(&b, "Content-Type: multipart/mixed; boundary=\"%s\"\r\n\r\n", mixedBoundary)

		// Body part
		fmt.Fprintf(&b, "--%s\r\n", mixedBoundary)

		if htmlBody != "" && textBody != "" {
			fmt.Fprintf(&b, "Content-Type: multipart/alternative; boundary=\"%s\"\r\n\r\n", altBoundary)
			fmt.Fprintf(&b, "--%s\r\n", altBoundary)
			writeTextPart(&b, contentTypeTextPlain, textBody)
			fmt.Fprintf(&b, "\r\n--%s\r\n", altBoundary)
			writeTextPart(&b, contentTypeTextHTML, htmlBody)
			fmt.Fprintf(&b, "\r\n--%s--\r\n", altBoundary)
		} else if htmlBody != "" {
			writeTextPart(&b, contentTypeTextHTML, htmlBody)
		} else {
			writeTextPart(&b, contentTypeTextPlain, textBody)
		}

		// Attachment parts
		for _, att := range attachments {
			fmt.Fprintf(&b, "\r\n--%s\r\n", mixedBoundary)
			contentType := att.ContentType
			if contentType == "" {
				contentType = "application/octet-stream"
			}
			fmt.Fprintf(&b, "Content-Type: %s\r\n", mime.FormatMediaType(contentType, map[string]string{"name": att.Filename}))
			b.WriteString("Content-Transfer-Encoding: base64\r\n")
			fmt.Fprintf(&b, "Content-Disposition: %s\r\n\r\n", mime.FormatMediaType("attachment", map[string]string{"filename": att.Filename}))

			// Content is already base64-encoded from the API request
			content := att.Content
			for len(content) > 76 {
				b.WriteString(content[:76])
				b.WriteString("\r\n")
				content = content[76:]
			}
			if len(content) > 0 {
				b.WriteString(content)
			}
		}
		fmt.Fprintf(&b, "\r\n--%s--\r\n", mixedBoundary)
	} else {
		altBoundary := newBoundary()
		if htmlBody != "" && textBody != "" {
			fmt.Fprintf(&b, "Content-Type: multipart/alternative; boundary=\"%s\"\r\n\r\n", altBoundary)
			fmt.Fprintf(&b, "--%s\r\n", altBoundary)
			writeTextPart(&b, contentTypeTextPlain, textBody)
			fmt.Fprintf(&b, "\r\n--%s\r\n", altBoundary)
			writeTextPart(&b, contentTypeTextHTML, htmlBody)
			fmt.Fprintf(&b, "\r\n--%s--\r\n", altBoundary)
		} else if htmlBody != "" {
			writeTextPart(&b, contentTypeTextHTML, htmlBody)
		} else {
			writeTextPart(&b, contentTypeTextPlain, textBody)
		}
	}

	return []byte(b.String())
}

// ValidateAttachments checks that attachments are within size limits.
func ValidateAttachments(attachments []models.Attachment, maxAttachmentSize, maxTotalSize int64) error {
	var totalSize int64
	for _, att := range attachments {
		if att.Filename == "" {
			return fmt.Errorf("attachment filename is required")
		}
		decoded, err := base64.StdEncoding.DecodeString(att.Content)
		if err != nil {
			return fmt.Errorf("attachment %q has invalid base64 content", att.Filename)
		}
		size := int64(len(decoded))
		if size > maxAttachmentSize {
			return fmt.Errorf("attachment %q exceeds maximum size of %d bytes", att.Filename, maxAttachmentSize)
		}
		totalSize += size
	}
	if totalSize > maxTotalSize {
		return fmt.Errorf("total attachment size exceeds maximum of %d bytes", maxTotalSize)
	}
	return nil
}