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.

16.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 worker

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net/mail"
	"strings"
	"time"

	"github.com/goposta/posta/internal/metrics"
	"github.com/goposta/posta/internal/models"
	"github.com/goposta/posta/internal/services/email"
	"github.com/goposta/posta/internal/services/webhook"
	"github.com/goposta/posta/internal/storage/blob"
	"github.com/goposta/posta/internal/storage/repositories"
	"github.com/hibiken/asynq"
	"github.com/jkaninda/logger"
)

// EmailSendHandler processes email:send tasks from the Asynq queue.
type EmailSendHandler struct {
	emailRepo       *repositories.EmailRepository
	smtpRepo        *repositories.SMTPRepository
	serverRepo      *repositories.ServerRepository
	domainRepo      *repositories.DomainRepository
	contactRepo     *repositories.ContactRepository
	messageRepo     *repositories.CampaignMessageRepository
	campaignRepo    *repositories.CampaignRepository
	suppressionRepo *repositories.SuppressionRepository
	bounceRepo      *repositories.BounceRepository
	autoSuppress    bool
	sender          *email.SMTPSender
	stamper         *email.Stamper
	dispatcher      *webhook.Dispatcher
	blobStore       blob.Store
	onSent          func()
	onFailed        func()
}

func NewEmailSendHandler(
	emailRepo *repositories.EmailRepository,
	smtpRepo *repositories.SMTPRepository,
	serverRepo *repositories.ServerRepository,
	domainRepo *repositories.DomainRepository,
	contactRepo *repositories.ContactRepository,
	dispatcher *webhook.Dispatcher,
) *EmailSendHandler {
	return &EmailSendHandler{
		emailRepo:   emailRepo,
		smtpRepo:    smtpRepo,
		serverRepo:  serverRepo,
		domainRepo:  domainRepo,
		contactRepo: contactRepo,
		sender:      email.NewSMTPSender(),
		dispatcher:  dispatcher,
	}
}

// SetBlobStore sets the blob storage backend for fetching attachment content.
func (h *EmailSendHandler) SetBlobStore(bs blob.Store) { h.blobStore = bs }

// SetCampaignMessageRepo sets the campaign message repository so that
// campaign message statuses are updated when emails are sent or fail.
func (h *EmailSendHandler) SetCampaignMessageRepo(r *repositories.CampaignMessageRepository) {
	h.messageRepo = r
}

// SetCampaignRepo lets the handler consult the campaign's live status before
// sending. When set, already-queued emails for cancelled/paused campaigns are
// dropped instead of dispatched.
func (h *EmailSendHandler) SetCampaignRepo(r *repositories.CampaignRepository) {
	h.campaignRepo = r
}

// SetStamper enables X-Mailer/X-Posta-* header stamping and optional
// X-Posta-Signature HMAC. Nil disables stamping.
func (h *EmailSendHandler) SetStamper(s *email.Stamper) {
	h.stamper = s
}

// SetSuppressionRepo enables auto-suppression of recipients permanently
// rejected by the receiving server.
func (h *EmailSendHandler) SetSuppressionRepo(r *repositories.SuppressionRepository) {
	h.suppressionRepo = r
}

// SetBounceRepo lets the handler record a hard bounce when a recipient is
// permanently rejected.
func (h *EmailSendHandler) SetBounceRepo(r *repositories.BounceRepository) {
	h.bounceRepo = r
}

// SetAutoSuppress toggles auto-suppression on permanent (5xx) recipient
// rejection. When false, such failures fall back to the normal retry path.
func (h *EmailSendHandler) SetAutoSuppress(enabled bool) {
	h.autoSuppress = enabled
}

// OnSent sets a callback invoked after each successful email send.
func (h *EmailSendHandler) OnSent(fn func()) { h.onSent = fn }

// OnFailed sets a callback invoked after each permanently failed email send.
func (h *EmailSendHandler) OnFailed(fn func()) { h.onFailed = fn }

// ProcessTask handles an email:send task.
func (h *EmailSendHandler) ProcessTask(ctx context.Context, t *asynq.Task) error {
	var payload EmailSendPayload
	if err := json.Unmarshal(t.Payload(), &payload); err != nil {
		return fmt.Errorf("failed to unmarshal payload: %w", err)
	}

	em, err := h.emailRepo.FindByID(payload.EmailID)
	if err != nil {
		return fmt.Errorf("email not found: %w", err)
	}

	// If this email was enqueued as part of a campaign, respect the live
	// campaign status. A paused campaign releases the message back to pending
	// so a Resume will re-dispatch it; cancelled drops it permanently.
	if h.messageRepo != nil && h.campaignRepo != nil {
		if msg, mErr := h.messageRepo.FindByEmailID(em.ID); mErr == nil {
			if camp, cErr := h.campaignRepo.FindByID(msg.CampaignID); cErr == nil {
				switch camp.Status {
				case models.CampaignStatusCancelled:
					_ = h.messageRepo.UpdateStatus(msg.ID, models.CampaignMsgSkipped, "campaign cancelled")
					em.Status = models.EmailStatusFailed
					em.ErrorMessage = "campaign cancelled"
					_ = h.emailRepo.Update(em)
					logger.Info("worker: dropping email for cancelled campaign", "email_id", em.ID, "campaign_id", camp.ID)
					return nil
				case models.CampaignStatusPaused:
					_ = h.messageRepo.UpdateStatus(msg.ID, models.CampaignMsgPending, "")
					em.Status = models.EmailStatusQueued
					_ = h.emailRepo.Update(em)
					logger.Info("worker: releasing email back to pending (campaign paused)", "email_id", em.ID, "campaign_id", camp.ID)
					return nil
				}
			}
		}
	}

	// Mark as processing
	em.Status = models.EmailStatusProcessing
	_ = h.emailRepo.Update(em)

	// Resolve sender address for validation/domain matching
	senderAddr := em.Sender
	if parsed, err := mail.ParseAddress(em.Sender); err == nil {
		senderAddr = parsed.Address
	}

	// Server selection:
	// 1. Try the workspace or user's own per-account SMTP server first.
	// 2. Fall back to a shared server whose allowed_domains covers the sender domain.
	var smtpServer *models.SMTPServer
	var sharedServerID uint // non-zero when a shared server is used

	var userServer *models.SMTPServer
	if em.WorkspaceID != nil {
		userServer, err = h.smtpRepo.FindFirstByWorkspaceID(*em.WorkspaceID)
	} else {
		userServer, err = h.smtpRepo.FindFirstByUserID(em.UserID)
	}
	if err == nil {
		// Validate the sender against the per-user allowed emails list
		if len(userServer.AllowedEmails) > 0 {
			allowed := false
			for _, e := range userServer.AllowedEmails {
				if e == senderAddr {
					allowed = true
					break
				}
			}
			if !allowed {
				h.markFailed(em, fmt.Sprintf("sender %q is not in the allowed emails list", em.Sender))
				return nil
			}
		}
		smtpServer = userServer
	} else {
		// No per-user server – look for a shared server by sender domain
		if h.serverRepo != nil {
			domain := senderDomain(senderAddr)
			if domain != "" {
				shared, serr := h.serverRepo.FindEnabledByDomain(domain)
				if serr == nil {
					// In strict mode the sender's domain must be ownership-verified.
					if shared.SecurityMode == models.ServerSecurityModeStrict {
						if h.domainRepo == nil || !h.domainRepo.IsOwnershipVerified(em.UserID, domain) {
							h.markFailed(em, fmt.Sprintf("shared server %q requires verified domain ownership for %q", shared.Name, domain))
							return nil
						}
					}
					smtpServer = shared.ToSMTPServer()
					sharedServerID = shared.ID
				}
			}
		}
	}

	if smtpServer == nil {
		h.markFailed(em, "no SMTP server configured for this account or domain")
		// Don't retry – adding a server won't happen automatically.
		return nil
	}

	em.SMTPHostname = smtpServer.Host
	_ = h.emailRepo.Update(em)

	// Auto-generate plain text from HTML if not provided
	if em.TextBody == "" && em.HTMLBody != "" {
		em.TextBody = email.HTMLToText(em.HTMLBody)
	}

	// Rebuild the attachments from the record, pulling blob-stored content if needed.
	attachments, err := email.LoadAttachments(ctx, em, h.blobStore)
	if err != nil {
		h.markFailed(em, fmt.Sprintf("failed to load attachments: %v", err))
		return nil
	}
	// An attachment with no payload would go out as a zero-byte file; fail loudly instead.
	for _, att := range attachments {
		if att.Content == "" {
			h.markFailed(em, fmt.Sprintf("attachment %q has no content", att.Filename))
			return nil
		}
	}

	// Parse custom headers from stored JSON
	var headers map[string]string
	if em.HeadersJSON != "" {
		_ = json.Unmarshal([]byte(em.HeadersJSON), &headers)
	}
	if headers == nil {
		headers = make(map[string]string)
	}

	// Drop recipients that became suppressed since this email was enqueued
	recipients := []string(em.Recipients)
	if h.suppressionRepo != nil {
		scope := repositories.ResourceScope{UserID: em.UserID, WorkspaceID: em.WorkspaceID}
		if filtered, fErr := h.suppressionRepo.FilterSuppressedForList(scope, recipients, em.UnsubscribeListID); fErr == nil {
			if len(filtered) == 0 {
				em.Status = models.EmailStatusSuppressed
				em.ErrorMessage = "all recipients are suppressed"
				_ = h.emailRepo.Update(em)
				if h.messageRepo != nil {
					if msg, mErr := h.messageRepo.FindByEmailID(em.ID); mErr == nil {
						_ = h.messageRepo.UpdateStatus(msg.ID, models.CampaignMsgSkipped, "recipient suppressed")
					}
				}
				logger.Info("worker: skipping email, all recipients suppressed", "id", em.ID)
				return nil
			}
			recipients = filtered
		}
	}

	// Stamp Posta headers. Campaign mail gets campaign-aware headers; everything
	// else gets transactional headers. A final HMAC signs the message identity.
	if h.stamper != nil {
		var campMsg *models.CampaignMessage
		if h.messageRepo != nil {
			if m, err := h.messageRepo.FindByEmailID(em.ID); err == nil {
				campMsg = m
			}
		}
		if campMsg != nil {
			// Opens and clicks are rewritten together in the tracking service's
			tracked := em.HTMLBody != "" && em.ListUnsubscribeURL != ""
			h.stamper.StampCampaign(
				headers, em,
				campMsg.CampaignID, campMsg.ID,
				tracked, tracked,
			)
		} else {
			h.stamper.StampTransactional(headers, em)
		}
		h.stamper.Sign(headers, em, recipients, em.Subject)
	}

	if err := h.sender.Send(smtpServer, em.Sender, recipients, em.Subject, em.HTMLBody, em.TextBody, attachments, headers, em.ListUnsubscribeURL, em.ListUnsubscribeMailto, em.ListUnsubscribePost); err != nil {
		// Increment the shared server's failure counter regardless of outcome.
		if sharedServerID != 0 && h.serverRepo != nil {
			go h.serverRepo.IncrementFailedCount(sharedServerID)
		}

		// A permanent rejection at RCPT TO (5xx, e.g. 550 user unknown) is a
		// hard bounce: suppress the recipient and stop retrying — retrying a
		// 5xx is pointless.
		if se, ok := permanentRejection(err); ok && h.autoSuppress {
			h.handlePermanentRejection(em, se)
			logger.Info("worker: recipient permanently rejected, suppressed", "id", em.ID, "recipient", se.Recipient, "code", se.Code)
			return nil
		}

		em.RetryCount++
		em.Status = models.EmailStatusFailed
		em.ErrorMessage = err.Error()
		_ = h.emailRepo.Update(em)
		logger.Debug("worker: email send failed, will retry", "id", em.ID, "attempt", em.RetryCount, "error", err)
		// Return error so Asynq retries the task
		return fmt.Errorf("SMTP send failed: %w", err)
	}

	// Success
	now := time.Now()
	em.Status = models.EmailStatusSent
	em.SentAt = &now
	em.ErrorMessage = ""
	_ = h.emailRepo.Update(em)
	// Increment the shared server's success counter
	if sharedServerID != 0 && h.serverRepo != nil {
		go h.serverRepo.IncrementSentCount(sharedServerID)
	}
	h.dispatcher.Dispatch(em.UserID, em.WorkspaceID, "email.sent", em.UUID, em.Sender)
	if h.onSent != nil {
		h.onSent()
	}
	if h.contactRepo != nil {
		go h.contactRepo.RecordSent(em.UserID, em.WorkspaceID, recipients)
	}
	if h.messageRepo != nil {
		if msg, err := h.messageRepo.FindByEmailID(em.ID); err == nil {
			_ = h.messageRepo.UpdateStatus(msg.ID, models.CampaignMsgSent, "")
		}
	}
	logger.Info("worker: email sent successfully", "id", em.ID)

	return nil
}

func (h *EmailSendHandler) markFailed(em *models.Email, reason string) {
	em.Status = models.EmailStatusFailed
	em.ErrorMessage = reason
	_ = h.emailRepo.Update(em)
	h.dispatcher.Dispatch(em.UserID, em.WorkspaceID, "email.failed", em.UUID, em.Sender)
	if h.onFailed != nil {
		h.onFailed()
	}
	if h.contactRepo != nil {
		go h.contactRepo.RecordFailed(em.UserID, em.WorkspaceID, em.Recipients)
	}
	if h.messageRepo != nil {
		if msg, err := h.messageRepo.FindByEmailID(em.ID); err == nil {
			_ = h.messageRepo.UpdateStatus(msg.ID, models.CampaignMsgFailed, reason)
		}
	}
}

// permanentRejection reports whether err represents a permanent recipient
// rejection (a 5xx reply at RCPT TO, e.g. 550 user unknown) that should trigger
// auto-suppression. Transient errors (4xx), connection failures, and failures
// at other SMTP stages (MAIL FROM, DATA) return false so they keep retrying.
func permanentRejection(err error) (*email.SendError, bool) {
	var se *email.SendError
	if errors.As(err, &se) && se.Permanent() && se.Stage == "RCPT TO" && se.Recipient != "" {
		return se, true
	}
	return nil, false
}

// handlePermanentRejection records a hard bounce, adds the recipient to the
// suppression list (idempotently) and marks the email failed without retrying.
// Called when the receiving server permanently rejects a recipient (5xx at
// RCPT TO, e.g. 550 user unknown).
func (h *EmailSendHandler) handlePermanentRejection(em *models.Email, se *email.SendError) {
	reason := se.Msg
	if reason == "" {
		reason = se.Error()
	}

	// Record a hard bounce for audit/metrics.
	if h.bounceRepo != nil {
		bounce := &models.Bounce{
			UserID:      em.UserID,
			WorkspaceID: em.WorkspaceID,
			EmailID:     em.ID,
			Recipient:   se.Recipient,
			Type:        models.BounceTypeHard,
			Reason:      reason,
		}
		if err := h.bounceRepo.Create(bounce); err == nil {
			metrics.IncrementBounce(string(models.BounceTypeHard))
		}
	}

	// Add to the suppression list (idempotent — ignore "already suppressed").
	if h.suppressionRepo != nil {
		suppression := &models.Suppression{
			UserID:      em.UserID,
			WorkspaceID: em.WorkspaceID,
			Email:       se.Recipient,
			Reason:      fmt.Sprintf("auto-suppressed: SMTP %d %s", se.Code, reason),
		}
		if err := h.suppressionRepo.Upsert(suppression); err == nil {
			metrics.IncrementSuppression()
		}
	}

	em.Status = models.EmailStatusFailed
	em.ErrorMessage = se.Error()
	_ = h.emailRepo.Update(em)

	h.dispatcher.Dispatch(em.UserID, em.WorkspaceID, "email.failed", em.UUID, em.Sender)
	if h.onFailed != nil {
		h.onFailed()
	}
	if h.contactRepo != nil {
		go h.contactRepo.RecordFailed(em.UserID, em.WorkspaceID, em.Recipients)
	}
	if h.messageRepo != nil {
		if msg, err := h.messageRepo.FindByEmailID(em.ID); err == nil {
			_ = h.messageRepo.UpdateStatus(msg.ID, models.CampaignMsgFailed, reason)
		}
	}
}

// senderDomain extracts the domain part of an email address.
func senderDomain(addr string) string {
	parts := strings.SplitN(addr, "@", 2)
	if len(parts) != 2 {
		return ""
	}
	return strings.ToLower(parts[1])
}

// ExhaustedErrorHandler marks emails as permanently failed when Asynq exhausts
// all retries. It implements asynq.ErrorHandler.
type ExhaustedErrorHandler struct {
	emailRepo  *repositories.EmailRepository
	dispatcher *webhook.Dispatcher
	onFailed   func()
}

func NewExhaustedErrorHandler(emailRepo *repositories.EmailRepository, dispatcher *webhook.Dispatcher, onFailed func()) *ExhaustedErrorHandler {
	return &ExhaustedErrorHandler{
		emailRepo:  emailRepo,
		dispatcher: dispatcher,
		onFailed:   onFailed,
	}
}

func (e *ExhaustedErrorHandler) HandleError(_ context.Context, t *asynq.Task, err error) {
	if t.Type() != TypeEmailSend {
		return
	}
	var payload EmailSendPayload
	if jsonErr := json.Unmarshal(t.Payload(), &payload); jsonErr != nil {
		logger.Error("exhausted handler: failed to unmarshal payload", "error", jsonErr)
		return
	}
	em, findErr := e.emailRepo.FindByID(payload.EmailID)
	if findErr != nil {
		return
	}
	em.Status = models.EmailStatusFailed
	em.ErrorMessage = fmt.Sprintf("permanently failed after retries: %v", err)
	_ = e.emailRepo.Update(em)
	e.dispatcher.Dispatch(em.UserID, em.WorkspaceID, "email.failed", em.UUID, em.Sender)
	if e.onFailed != nil {
		e.onFailed()
	}
	logger.Error("worker: email permanently failed", "id", em.ID, "error", err)
}