Send mailing list emails

Signed-off-by: Sacha Al Himdani <sacha@getprobo.com>

pkg/mailman/compliance_mailing_list.go

@@ -0,0 +1,161 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package mailman
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"go.gearno.de/kit/pg"
+	"go.probo.inc/probo/packages/emails"
+	"go.probo.inc/probo/pkg/baseurl"
+	"go.probo.inc/probo/pkg/coredata"
+	"go.probo.inc/probo/pkg/gid"
+	"go.probo.inc/probo/pkg/mail"
+)
+
+func (s *Service) SubscriptionConfirmationEmailConfig(
+	ctx context.Context,
+	mailingListID gid.GID,
+) (emails.PresenterConfig, string, *mail.Addr, error) {
+	cfg, orgName, _, replyTo, err := s.mailingListEmailConfig(ctx, mailingListID)
+	return cfg, orgName, replyTo, err
+}
+
+func (s *Service) UnsubscribeEmailConfig(
+	ctx context.Context,
+	mailingListID gid.GID,
+) (emails.PresenterConfig, string, *mail.Addr, error) {
+	cfg, orgName, _, replyTo, err := s.mailingListEmailConfig(ctx, mailingListID)
+	return cfg, orgName, replyTo, err
+}
+
+func (s *Service) UpdateEmailConfig(
+	ctx context.Context,
+	mailingListID gid.GID,
+) (emails.PresenterConfig, string, string, *mail.Addr, error) {
+	return s.mailingListEmailConfig(ctx, mailingListID)
+}
+
+func (s *Service) mailingListEmailConfig(
+	ctx context.Context,
+	mailingListID gid.GID,
+) (emails.PresenterConfig, string, string, *mail.Addr, error) {
+	var (
+		mailingList    = &coredata.MailingList{}
+		compliancePage = &coredata.TrustCenter{}
+		organization   = &coredata.Organization{}
+		customDomain   *coredata.CustomDomain
+		logoFile       = &coredata.File{}
+		defaultCfg     = emails.DefaultPresenterConfig(s.bucket, s.apiBaseURL.String())
+	)
+
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			if err := mailingList.LoadByID(ctx, conn, scope, mailingListID); err != nil {
+				return fmt.Errorf("cannot load mailing list: %w", err)
+			}
+			if err := compliancePage.LoadByMailingListID(ctx, conn, scope, mailingListID); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return err
+				}
+				return fmt.Errorf("cannot load compliance page: %w", err)
+			}
+			if compliancePage.LogoFileID != nil {
+				if err := logoFile.LoadByID(ctx, conn, scope, *compliancePage.LogoFileID); err != nil {
+					return fmt.Errorf("cannot load logo file: %w", err)
+				}
+			}
+			if err := organization.LoadByID(ctx, conn, scope, compliancePage.OrganizationID); err != nil {
+				return fmt.Errorf("cannot load organization: %w", err)
+			}
+			customDomain = &coredata.CustomDomain{}
+			if err := customDomain.LoadByOrganizationID(ctx, conn, scope, organization.ID); err != nil {
+				if !errors.Is(err, coredata.ErrResourceNotFound) {
+					return fmt.Errorf("cannot load custom domain: %w", err)
+				}
+			}
+			return nil
+		},
+	)
+	if err != nil {
+		return defaultCfg, "", "", nil, err
+	}
+
+	cfg, compliancePageURL, err := s.presenterConfigFromTrustCenter(compliancePage, organization, customDomain, logoFile)
+	if err != nil {
+		return defaultCfg, "", "", nil, err
+	}
+
+	compliancePageBase, err := baseurl.Parse(compliancePageURL)
+	if err != nil {
+		return defaultCfg, "", "", nil, fmt.Errorf("cannot parse compliance page URL: %w", err)
+	}
+
+	updatesPageURL, err := compliancePageBase.AppendPath("/updates").String()
+	if err != nil {
+		return defaultCfg, "", "", nil, fmt.Errorf("cannot build updates page URL: %w", err)
+	}
+
+	return cfg, organization.Name, updatesPageURL, mailingList.ReplyTo, nil
+}
+
+func (s *Service) presenterConfigFromTrustCenter(
+	compliancePage *coredata.TrustCenter,
+	organization *coredata.Organization,
+	customDomain *coredata.CustomDomain,
+	logoFile *coredata.File,
+) (emails.PresenterConfig, string, error) {
+	cfg := emails.DefaultPresenterConfig(s.bucket, s.apiBaseURL.String())
+
+	compliancePageBase := s.apiBaseURL.WithPath("/trust/" + compliancePage.ID.String())
+
+	if customDomain != nil && customDomain.SSLStatus == coredata.CustomDomainSSLStatusActive {
+		customBase, err := baseurl.Parse("https://" + customDomain.Domain)
+		if err != nil {
+			return cfg, "", fmt.Errorf("cannot parse custom domain URL: %w", err)
+		}
+		compliancePageBase = customBase.WithPath("")
+	}
+
+	compliancePageURL, err := compliancePageBase.String()
+	if err != nil {
+		return cfg, "", fmt.Errorf("cannot build compliance page URL: %w", err)
+	}
+
+	cfg.BaseURL = compliancePageURL
+
+	if compliancePage.LogoFileID != nil && logoFile != nil && logoFile.FileKey != "" {
+		cfg.SenderCompanyLogo = emails.Asset{
+			Name:       logoFile.FileName,
+			ObjectKey:  logoFile.FileKey,
+			BucketName: logoFile.BucketName,
+			MimeType:   logoFile.MimeType,
+		}
+		cfg.SenderCompanyName = organization.Name
+		if organization.WebsiteURL != nil {
+			cfg.SenderCompanyWebsiteURL = *organization.WebsiteURL
+		}
+		if organization.HeadquarterAddress != nil {
+			cfg.SenderCompanyHeadquarterAddress = *organization.HeadquarterAddress
+		}
+	}
+
+	return cfg, compliancePageURL, nil
+}

pkg/mailman/errors.go

@@ -17,7 +17,9 @@ package mailman
 import "errors"
 
 var (
-	ErrMailingListNotFound    = errors.New("mailing list not found")
-	ErrSubscriberNotFound     = errors.New("mailing list subscriber not found")
-	ErrSubscriberAlreadyExist = errors.New("mailing list subscriber already exists")
+	ErrMailingListNotFound          = errors.New("mailing list not found")
+	ErrSubscriberNotFound           = errors.New("mailing list subscriber not found")
+	ErrSubscriberAlreadyExist       = errors.New("mailing list subscriber already exists")
+	ErrMailingListUpdateNotFound    = errors.New("mailing list update not found")
+	ErrMailingListUpdateAlreadySent = errors.New("mailing list update already sent")
 )

pkg/mailman/mailing_list_worker.go

@@ -0,0 +1,230 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package mailman
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"go.gearno.de/kit/log"
+	"go.gearno.de/kit/pg"
+	"go.probo.inc/probo/pkg/coredata"
+)
+
+type (
+	MailingListWorker struct {
+		service        *Service
+		pg             *pg.Client
+		logger         *log.Logger
+		interval       time.Duration
+		staleAfter     time.Duration
+		maxConcurrency int
+	}
+
+	MailingListWorkerOption func(*MailingListWorker)
+)
+
+func WithMailingListWorkerInterval(d time.Duration) MailingListWorkerOption {
+	return func(w *MailingListWorker) { w.interval = d }
+}
+
+func WithMailingListWorkerStaleAfter(d time.Duration) MailingListWorkerOption {
+	return func(w *MailingListWorker) { w.staleAfter = d }
+}
+
+func WithMailingListWorkerMaxConcurrency(n int) MailingListWorkerOption {
+	return func(w *MailingListWorker) {
+		if n > 0 {
+			w.maxConcurrency = n
+		}
+	}
+}
+
+func NewMailingListWorker(
+	service *Service,
+	pgClient *pg.Client,
+	logger *log.Logger,
+	opts ...MailingListWorkerOption,
+) *MailingListWorker {
+	w := &MailingListWorker{
+		service:        service,
+		pg:             pgClient,
+		logger:         logger,
+		interval:       10 * time.Second,
+		staleAfter:     5 * time.Minute,
+		maxConcurrency: 5,
+	}
+
+	for _, opt := range opts {
+		opt(w)
+	}
+
+	return w
+}
+
+func (w *MailingListWorker) Run(ctx context.Context) error {
+	var (
+		wg  sync.WaitGroup
+		sem = make(chan struct{}, w.maxConcurrency)
+	)
+
+	defer wg.Wait()
+
+LOOP:
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-time.After(w.interval):
+		// From there we should not accept cancellations anymore.
+		nonCancelableCtx := context.WithoutCancel(ctx)
+		w.recoverStaleRows(nonCancelableCtx)
+
+		for {
+			if err := w.processNext(ctx, sem, &wg); err != nil {
+				if !errors.Is(err, coredata.ErrResourceNotFound) {
+					w.logger.ErrorCtx(nonCancelableCtx, "cannot claim mailing list update", log.Error(err))
+				}
+				break
+			}
+		}
+
+		goto LOOP
+	}
+}
+
+func (w *MailingListWorker) processNext(ctx context.Context, sem chan struct{}, wg *sync.WaitGroup) error {
+	select {
+	case sem <- struct{}{}:
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+
+	var (
+		mlu              coredata.MailingListUpdate
+		now              = time.Now()
+		nonCancelableCtx = context.WithoutCancel(ctx)
+	)
+
+	if err := w.pg.WithTx(
+		nonCancelableCtx,
+		func(tx pg.Conn) error {
+			if err := mlu.LoadNextEnqueuedForUpdateSkipLocked(nonCancelableCtx, tx); err != nil {
+				return err
+			}
+
+			scope := coredata.NewScopeFromObjectID(mlu.ID)
+			mlu.Status = coredata.MailingListUpdateStatusProcessing
+			mlu.UpdatedAt = now
+
+			if err := mlu.Update(nonCancelableCtx, tx, scope); err != nil {
+				return fmt.Errorf("cannot claim mailing list update: %w", err)
+			}
+
+			return nil
+		},
+	); err != nil {
+		<-sem
+		return err
+	}
+
+	wg.Add(1)
+	go func(mlu coredata.MailingListUpdate) {
+		defer wg.Done()
+		defer func() { <-sem }()
+
+		if err := w.sendAndCommit(nonCancelableCtx, &mlu); err != nil {
+			w.logger.ErrorCtx(nonCancelableCtx, "cannot send mailing list update",
+				log.Error(err),
+				log.String("mailing_list_update_id", mlu.ID.String()),
+			)
+
+			if err := w.resetEnqueued(nonCancelableCtx, &mlu); err != nil {
+				w.logger.ErrorCtx(nonCancelableCtx, "cannot reset mailing list update to enqueued",
+					log.Error(err),
+					log.String("mailing_list_update_id", mlu.ID.String()),
+				)
+			}
+		}
+	}(mlu)
+
+	return nil
+}
+
+func (w *MailingListWorker) sendAndCommit(ctx context.Context, mlu *coredata.MailingListUpdate) error {
+	if err := w.service.CreateUpdateEmails(ctx, mlu.MailingListID, mlu.ID, mlu.Title, mlu.Body); err != nil {
+		return fmt.Errorf("cannot create update emails: %w", err)
+	}
+
+	return w.pg.WithTx(
+		ctx,
+		func(tx pg.Conn) error {
+			scope := coredata.NewScopeFromObjectID(mlu.ID)
+
+			var current coredata.MailingListUpdate
+			if err := current.LoadByID(ctx, tx, scope, mlu.ID); err != nil {
+				return fmt.Errorf("cannot reload mailing list update: %w", err)
+			}
+
+			if current.Status != coredata.MailingListUpdateStatusProcessing {
+				return fmt.Errorf("unexpected status %s, expected PROCESSING", current.Status)
+			}
+
+			mlu.Status = coredata.MailingListUpdateStatusSent
+			mlu.UpdatedAt = time.Now()
+
+			if err := mlu.Update(ctx, tx, scope); err != nil {
+				return fmt.Errorf("cannot mark mailing list update as sent: %w", err)
+			}
+
+			return nil
+		},
+	)
+}
+
+func (w *MailingListWorker) resetEnqueued(ctx context.Context, mlu *coredata.MailingListUpdate) error {
+	return w.pg.WithTx(
+		ctx,
+		func(tx pg.Conn) error {
+			scope := coredata.NewScopeFromObjectID(mlu.ID)
+			mlu.Status = coredata.MailingListUpdateStatusEnqueued
+			mlu.UpdatedAt = time.Now()
+
+			if err := mlu.Update(ctx, tx, scope); err != nil {
+				return fmt.Errorf("cannot reset mailing list update: %w", err)
+			}
+
+			return nil
+		},
+	)
+}
+
+func (w *MailingListWorker) recoverStaleRows(ctx context.Context) {
+	err := w.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			if err := coredata.ResetStaleProcessingMailingListUpdates(ctx, conn, w.staleAfter); err != nil {
+				return fmt.Errorf("cannot reset stale processing mailing list updates: %w", err)
+			}
+			return nil
+		},
+	)
+
+	if err != nil {
+		w.logger.ErrorCtx(ctx, "cannot recover stale processing mailing list updates", log.Error(err))
+	}
+}

pkg/mailman/service.go

@@ -20,19 +20,35 @@ import (
 	"fmt"
 	"time"
 
+	"go.gearno.de/kit/log"
 	"go.gearno.de/kit/pg"
+	"go.probo.inc/probo/packages/emails"
+	"go.probo.inc/probo/pkg/baseurl"
 	"go.probo.inc/probo/pkg/coredata"
+	"go.probo.inc/probo/pkg/crypto/cipher"
+	"go.probo.inc/probo/pkg/filemanager"
 	"go.probo.inc/probo/pkg/gid"
 	"go.probo.inc/probo/pkg/mail"
 	"go.probo.inc/probo/pkg/page"
 )
 
+const (
+	pathUnsubscribe = "/mail-actions/unsubscribe"
+	pathConfirm     = "/mail-actions/confirm"
+)
+
 type Service struct {
-	pg *pg.Client
+	pg            *pg.Client
+	fm            *filemanager.Service
+	tokenSecret   string
+	apiBaseURL    *baseurl.BaseURL
+	bucket        string
+	encryptionKey cipher.EncryptionKey
+	logger        *log.Logger
 }
 
-func NewService(pgClient *pg.Client) *Service {
-	return &Service{pg: pgClient}
+func NewService(pgClient *pg.Client, fm *filemanager.Service, tokenSecret string, apiBaseURL *baseurl.BaseURL, bucket string, encryptionKey cipher.EncryptionKey, logger *log.Logger) *Service {
+	return &Service{pg: pgClient, fm: fm, tokenSecret: tokenSecret, apiBaseURL: apiBaseURL, bucket: bucket, encryptionKey: encryptionKey, logger: logger}
 }
 
 func (s *Service) UpdateMailingList(
@@ -40,8 +56,8 @@ func (s *Service) UpdateMailingList(
 	id gid.GID,
 	replyTo *mail.Addr,
 ) (*coredata.MailingList, error) {
+	var ml coredata.MailingList
 	scope := coredata.NewScopeFromObjectID(id)
-	ml := coredata.MailingList{}
 
 	err := s.pg.WithConn(
 		ctx,
@@ -105,8 +121,12 @@ func (s *Service) CreateSubscriber(
 	fullName string,
 ) (*coredata.MailingListSubscriber, error) {
 	scope := coredata.NewScopeFromObjectID(mailingListID)
-	now := time.Now()
+	emailRecord, err := s.buildConfirmationMail(ctx, mailingListID, email, fullName)
+	if err != nil {
+		return nil, fmt.Errorf("cannot build confirmation mail: %w", err)
+	}
 
+	now := time.Now()
 	subscriber := &coredata.MailingListSubscriber{
 		ID:            gid.New(scope.GetTenantID(), coredata.MailingListSubscriberEntityType),
 		MailingListID: mailingListID,
@@ -117,53 +137,150 @@ func (s *Service) CreateSubscriber(
 		UpdatedAt:     now,
 	}
 
-	err := s.pg.WithConn(
+	if err := s.pg.WithTx(
 		ctx,
-		func(conn pg.Conn) error {
-			ml := coredata.MailingList{}
-			if err := ml.LoadByID(ctx, conn, scope, mailingListID); err != nil {
+		func(tx pg.Conn) error {
+			var ml coredata.MailingList
+			if err := ml.LoadByID(ctx, tx, scope, mailingListID); err != nil {
 				return fmt.Errorf("cannot load mailing list: %w", err)
 			}
 			subscriber.OrganizationID = ml.OrganizationID
 
-			if err := subscriber.Insert(ctx, conn, scope); err != nil {
+			if err := subscriber.Insert(ctx, tx, scope); err != nil {
 				if errors.Is(err, coredata.ErrResourceAlreadyExists) {
 					return ErrSubscriberAlreadyExist
 				}
 				return fmt.Errorf("cannot insert mailing list subscriber: %w", err)
 			}
 
+			if err := emailRecord.Insert(ctx, tx); err != nil {
+				return fmt.Errorf("cannot insert subscription confirmation email: %w", err)
+			}
+
 			return nil
 		},
-	)
-	if err != nil {
+	); err != nil {
 		return nil, err
 	}
 
 	return subscriber, nil
 }
 
+func (s *Service) UnsubscribeByEmail(
+	ctx context.Context,
+	mailingListID gid.GID,
+	email mail.Addr,
+) error {
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+	return s.pg.WithTx(
+		ctx,
+		func(tx pg.Conn) error {
+			var subscriber coredata.MailingListSubscriber
+			if err := subscriber.LoadByMailingListIDAndEmail(ctx, tx, scope, mailingListID, email); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrSubscriberNotFound
+				}
+				return fmt.Errorf("cannot load mailing list subscriber: %w", err)
+			}
+
+			wasConfirmed := subscriber.Status == coredata.MailingListSubscriberStatusConfirmed
+
+			if err := subscriber.Delete(ctx, tx, scope); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrSubscriberNotFound
+				}
+				return fmt.Errorf("cannot delete mailing list subscriber: %w", err)
+			}
+
+			if wasConfirmed {
+				emailRecord, err := s.buildUnsubscriptionMail(ctx, mailingListID, subscriber.Email, subscriber.FullName)
+				if err != nil {
+					return fmt.Errorf("cannot build unsubscription email: %w", err)
+				}
+
+				if err := emailRecord.Insert(ctx, tx); err != nil {
+					return fmt.Errorf("cannot insert unsubscription email: %w", err)
+				}
+			}
+
+			return nil
+		},
+	)
+}
+
+func (s *Service) ConfirmSubscriberByEmail(
+	ctx context.Context,
+	mailingListID gid.GID,
+	email mail.Addr,
+) error {
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+
+	return s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			var subscriber coredata.MailingListSubscriber
+			if err := subscriber.LoadByMailingListIDAndEmail(ctx, conn, scope, mailingListID, email); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrSubscriberNotFound
+				}
+				return fmt.Errorf("cannot load mailing list subscriber: %w", err)
+			}
+
+			subscriber.Status = coredata.MailingListSubscriberStatusConfirmed
+			subscriber.UpdatedAt = time.Now()
+
+			if err := subscriber.Update(ctx, conn, scope); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrSubscriberNotFound
+				}
+				return fmt.Errorf("cannot update mailing list subscriber: %w", err)
+			}
+
+			return nil
+		},
+	)
+}
+
 func (s *Service) DeleteSubscriber(
 	ctx context.Context,
 	id gid.GID,
 ) error {
 	scope := coredata.NewScopeFromObjectID(id)
 
-	err := s.pg.WithConn(
+	return s.pg.WithTx(
 		ctx,
-		func(conn pg.Conn) error {
-			subscriber := coredata.MailingListSubscriber{ID: id}
-			if err := subscriber.Delete(ctx, conn, scope); err != nil {
+		func(tx pg.Conn) error {
+			var subscriber coredata.MailingListSubscriber
+			if err := subscriber.LoadByID(ctx, tx, scope, id); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrSubscriberNotFound
+				}
+				return fmt.Errorf("cannot load mailing list subscriber: %w", err)
+			}
+
+			wasConfirmed := subscriber.Status == coredata.MailingListSubscriberStatusConfirmed
+
+			if err := subscriber.Delete(ctx, tx, scope); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrSubscriberNotFound
+				}
 				return fmt.Errorf("cannot delete mailing list subscriber: %w", err)
 			}
+
+			if wasConfirmed {
+				emailRecord, err := s.buildUnsubscriptionMail(ctx, subscriber.MailingListID, subscriber.Email, subscriber.FullName)
+				if err != nil {
+					return fmt.Errorf("cannot build unsubscription email: %w", err)
+				}
+
+				if err := emailRecord.Insert(ctx, tx); err != nil {
+					return fmt.Errorf("cannot insert unsubscription email: %w", err)
+				}
+			}
+
 			return nil
 		},
 	)
-	if err != nil {
-		return err
-	}
-
-	return nil
 }
 
 func (s *Service) CountSubscribers(
@@ -171,7 +288,7 @@ func (s *Service) CountSubscribers(
 	mailingListID gid.GID,
 ) (int, error) {
 	scope := coredata.NewScopeFromObjectID(mailingListID)
-	count := 0
+	var count int
 
 	err := s.pg.WithConn(
 		ctx,
@@ -197,7 +314,7 @@ func (s *Service) ListSubscribers(
 	cursor *page.Cursor[coredata.MailingListSubscriberOrderField],
 ) (*page.Page[*coredata.MailingListSubscriber, coredata.MailingListSubscriberOrderField], error) {
 	scope := coredata.NewScopeFromObjectID(mailingListID)
-	subscribers := coredata.MailingListSubscribers{}
+	var subscribers coredata.MailingListSubscribers
 
 	err := s.pg.WithConn(
 		ctx,
@@ -214,3 +331,386 @@ func (s *Service) ListSubscribers(
 
 	return page.NewPage(subscribers, cursor), nil
 }
+
+func (s *Service) CreateMailingListUpdate(
+	ctx context.Context,
+	mailingListID gid.GID,
+	title string,
+	body string,
+) (*coredata.MailingListUpdate, error) {
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+	now := time.Now()
+
+	mlu := &coredata.MailingListUpdate{
+		ID:            gid.New(scope.GetTenantID(), coredata.MailingListUpdateEntityType),
+		MailingListID: mailingListID,
+		Title:         title,
+		Body:          body,
+		Status:        coredata.MailingListUpdateStatusDraft,
+		CreatedAt:     now,
+		UpdatedAt:     now,
+	}
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			var ml coredata.MailingList
+			if err := ml.LoadByID(ctx, conn, scope, mailingListID); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrMailingListNotFound
+				}
+				return fmt.Errorf("cannot load mailing list: %w", err)
+			}
+
+			mlu.OrganizationID = ml.OrganizationID
+
+			if err := mlu.Insert(ctx, conn, scope); err != nil {
+				return fmt.Errorf("cannot insert mailing list update: %w", err)
+			}
+
+			return nil
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return mlu, nil
+}
+
+func (s *Service) GetMailingListUpdate(
+	ctx context.Context,
+	id gid.GID,
+) (*coredata.MailingListUpdate, error) {
+	scope := coredata.NewScopeFromObjectID(id)
+	var mlu coredata.MailingListUpdate
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			if err := mlu.LoadByID(ctx, conn, scope, id); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrMailingListUpdateNotFound
+				}
+				return fmt.Errorf("cannot load mailing list update: %w", err)
+			}
+			return nil
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return &mlu, nil
+}
+
+func (s *Service) UpdateMailingListUpdate(
+	ctx context.Context,
+	id gid.GID,
+	title string,
+	body string,
+) (*coredata.MailingListUpdate, error) {
+	scope := coredata.NewScopeFromObjectID(id)
+	var mlu coredata.MailingListUpdate
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			if err := mlu.LoadByID(ctx, conn, scope, id); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrMailingListUpdateNotFound
+				}
+				return fmt.Errorf("cannot load mailing list update: %w", err)
+			}
+
+			if mlu.Status != coredata.MailingListUpdateStatusDraft {
+				return ErrMailingListUpdateAlreadySent
+			}
+
+			mlu.Title = title
+			mlu.Body = body
+			mlu.UpdatedAt = time.Now()
+
+			if err := mlu.Update(ctx, conn, scope); err != nil {
+				return fmt.Errorf("cannot update mailing list update: %w", err)
+			}
+
+			return nil
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return &mlu, nil
+}
+
+func (s *Service) SendMailingListUpdate(
+	ctx context.Context,
+	id gid.GID,
+) (*coredata.MailingListUpdate, error) {
+	scope := coredata.NewScopeFromObjectID(id)
+	var mlu coredata.MailingListUpdate
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			if err := mlu.LoadByID(ctx, conn, scope, id); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrMailingListUpdateNotFound
+				}
+				return fmt.Errorf("cannot load mailing list update: %w", err)
+			}
+
+			if mlu.Status != coredata.MailingListUpdateStatusDraft {
+				return ErrMailingListUpdateAlreadySent
+			}
+
+			mlu.Status = coredata.MailingListUpdateStatusEnqueued
+			mlu.UpdatedAt = time.Now()
+
+			if err := mlu.Update(ctx, conn, scope); err != nil {
+				return fmt.Errorf("cannot queue mailing list update for sending: %w", err)
+			}
+
+			return nil
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return &mlu, nil
+}
+
+func (s *Service) DeleteMailingListUpdate(
+	ctx context.Context,
+	id gid.GID,
+) error {
+	scope := coredata.NewScopeFromObjectID(id)
+
+	return s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			mlu := coredata.MailingListUpdate{ID: id}
+			if err := mlu.Delete(ctx, conn, scope); err != nil {
+				if errors.Is(err, coredata.ErrResourceNotFound) {
+					return ErrMailingListUpdateNotFound
+				}
+				return fmt.Errorf("cannot delete mailing list update: %w", err)
+			}
+			return nil
+		},
+	)
+}
+
+func (s *Service) ListMailingListUpdates(
+	ctx context.Context,
+	mailingListID gid.GID,
+	cursor *page.Cursor[coredata.MailingListUpdateOrderField],
+) (*page.Page[*coredata.MailingListUpdate, coredata.MailingListUpdateOrderField], error) {
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+	var items coredata.MailingListUpdateItems
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			if err := items.LoadByMailingListID(ctx, conn, scope, mailingListID, cursor); err != nil {
+				return fmt.Errorf("cannot load mailing list updates: %w", err)
+			}
+			return nil
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return page.NewPage(items, cursor), nil
+}
+
+func (s *Service) ListSentMailingListUpdates(
+	ctx context.Context,
+	mailingListID gid.GID,
+	cursor *page.Cursor[coredata.MailingListUpdateOrderField],
+) (*page.Page[*coredata.MailingListUpdate, coredata.MailingListUpdateOrderField], error) {
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+	var items coredata.MailingListUpdateItems
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			if err := items.LoadSentByMailingListID(ctx, conn, scope, mailingListID, cursor); err != nil {
+				return fmt.Errorf("cannot load sent mailing list updates: %w", err)
+			}
+			return nil
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return page.NewPage(items, cursor), nil
+}
+
+func (s *Service) CountMailingListUpdates(
+	ctx context.Context,
+	mailingListID gid.GID,
+) (int, error) {
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+	var count int
+
+	err := s.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			var items coredata.MailingListUpdateItems
+			var err error
+			count, err = items.CountByMailingListID(ctx, conn, scope, mailingListID)
+			if err != nil {
+				return fmt.Errorf("cannot count mailing list updates: %w", err)
+			}
+			return nil
+		},
+	)
+	if err != nil {
+		return 0, err
+	}
+
+	return count, nil
+}
+
+func (s *Service) CreateUpdateEmails(
+	ctx context.Context,
+	mailingListID gid.GID,
+	mailingListUpdateID gid.GID,
+	updateTitle string,
+	updateBody string,
+) error {
+	scope := coredata.NewScopeFromObjectID(mailingListID)
+
+	presenterCfg, orgName, compliancePageURL, replyTo, err := s.UpdateEmailConfig(ctx, mailingListID)
+	if err != nil {
+		return fmt.Errorf("cannot get update email config: %w", err)
+	}
+
+	return s.pg.WithTx(
+		ctx,
+		func(tx pg.Conn) error {
+			var subscribers coredata.MailingListSubscribers
+			if err := subscribers.LoadAllConfirmedByMailingListID(ctx, tx, scope, mailingListID); err != nil {
+				return fmt.Errorf("cannot load confirmed subscribers: %w", err)
+			}
+
+			if len(subscribers) == 0 {
+				return nil
+			}
+
+			emailRecords := make(coredata.Emails, 0, len(subscribers))
+			for _, sub := range subscribers {
+				unsubscribeURL, err := s.buildUnsubscribeURL(mailingListID, sub.Email)
+				if err != nil {
+					return fmt.Errorf("cannot generate unsubscribe URL: %w", err)
+				}
+
+				subject, textBody, htmlBody, err := emails.NewPresenterFromConfig(s.fm, presenterCfg, sub.FullName).
+					RenderMailingListNews(ctx, orgName, updateTitle, updateBody, compliancePageURL, unsubscribeURL)
+				if err != nil {
+					return fmt.Errorf("cannot render mailing list update email: %w", err)
+				}
+
+				emailRecords = append(
+					emailRecords,
+					coredata.NewEmail(
+						sub.FullName,
+						sub.Email,
+						subject,
+						textBody,
+						htmlBody,
+						&coredata.EmailOptions{
+							ReplyTo:             replyTo,
+							UnsubscribeURL:      &unsubscribeURL,
+							MailingListUpdateID: &mailingListUpdateID,
+						},
+					),
+				)
+			}
+
+			if err := emailRecords.BulkInsert(ctx, tx); err != nil {
+				return fmt.Errorf("cannot bulk insert update emails: %w", err)
+			}
+
+			return nil
+		},
+	)
+}
+
+func (s *Service) buildConfirmationMail(
+	ctx context.Context,
+	mailingListID gid.GID,
+	email mail.Addr,
+	fullName string,
+) (*coredata.Email, error) {
+	unsubscribeURL, err := s.buildUnsubscribeURL(mailingListID, email)
+	if err != nil {
+		return nil, fmt.Errorf("cannot generate unsubscribe URL: %w", err)
+	}
+
+	confirmURL, err := s.buildConfirmURL(mailingListID, email)
+	if err != nil {
+		return nil, fmt.Errorf("cannot generate confirm URL: %w", err)
+	}
+
+	presenterCfg, orgName, replyTo, err := s.SubscriptionConfirmationEmailConfig(ctx, mailingListID)
+	if err != nil {
+		return nil, fmt.Errorf("cannot get subscription confirmation email config: %w", err)
+	}
+
+	subject, textBody, htmlBody, err := emails.NewPresenterFromConfig(s.fm, presenterCfg, fullName).
+		RenderMailingListSubscription(ctx, orgName, confirmURL, unsubscribeURL)
+	if err != nil {
+		return nil, fmt.Errorf("cannot render subscription confirmation email: %w", err)
+	}
+
+	return coredata.NewEmail(fullName, email, subject, textBody, htmlBody, &coredata.EmailOptions{ReplyTo: replyTo, UnsubscribeURL: &unsubscribeURL}), nil
+}
+
+func (s *Service) buildUnsubscriptionMail(
+	ctx context.Context,
+	mailingListID gid.GID,
+	email mail.Addr,
+	fullName string,
+) (*coredata.Email, error) {
+	presenterCfg, orgName, replyTo, err := s.UnsubscribeEmailConfig(ctx, mailingListID)
+	if err != nil {
+		return nil, fmt.Errorf("cannot get unsubscription email config: %w", err)
+	}
+
+	subject, textBody, htmlBody, err := emails.NewPresenterFromConfig(s.fm, presenterCfg, fullName).
+		RenderMailingListUnsubscription(ctx, orgName)
+	if err != nil {
+		return nil, fmt.Errorf("cannot render unsubscription email: %w", err)
+	}
+
+	return coredata.NewEmail(fullName, email, subject, textBody, htmlBody, &coredata.EmailOptions{ReplyTo: replyTo}), nil
+}
+
+func (s *Service) buildUnsubscribeURL(mailingListID gid.GID, email mail.Addr) (string, error) {
+	if s.tokenSecret == "" {
+		return "", nil
+	}
+	token, err := newUnsubscribeToken(s.tokenSecret, mailingListID, email)
+	if err != nil {
+		return "", err
+	}
+	return s.apiBaseURL.WithPath(pathUnsubscribe).WithQuery("token", token).String()
+}
+
+func (s *Service) buildConfirmURL(mailingListID gid.GID, email mail.Addr) (string, error) {
+	if s.tokenSecret == "" {
+		return "", nil
+	}
+	token, err := newConfirmToken(s.tokenSecret, mailingListID, email)
+	if err != nil {
+		return "", err
+	}
+	return s.apiBaseURL.WithPath(pathConfirm).WithQuery("token", token).String()
+}

pkg/mailman/token.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package mailman
+
+import (
+	"fmt"
+	"time"
+
+	"go.probo.inc/probo/pkg/gid"
+	"go.probo.inc/probo/pkg/mail"
+	"go.probo.inc/probo/pkg/statelesstoken"
+)
+
+const (
+	TokenTypeUnsubscribe = "mailing_list_unsubscribe"
+	TokenTypeConfirm     = "mailing_list_confirm_subscription"
+
+	unsubscribeTokenExpiry = 365 * 24 * time.Hour
+	confirmTokenExpiry     = 15 * 24 * time.Hour
+)
+
+type UnsubscribeTokenData struct {
+	MailingListID gid.GID   `json:"m"`
+	Email         mail.Addr `json:"e"`
+}
+
+func newUnsubscribeToken(secret string, mailingListID gid.GID, recipientEmail mail.Addr) (string, error) {
+	return statelesstoken.NewToken(
+		secret,
+		TokenTypeUnsubscribe,
+		unsubscribeTokenExpiry,
+		UnsubscribeTokenData{
+			MailingListID: mailingListID,
+			Email:         recipientEmail,
+		},
+	)
+}
+
+func ValidateUnsubscribeToken(secret, tokenString string) (*UnsubscribeTokenData, error) {
+	payload, err := statelesstoken.ValidateToken[UnsubscribeTokenData](secret, TokenTypeUnsubscribe, tokenString)
+	if err != nil {
+		return nil, fmt.Errorf("cannot validate unsubscribe token: %w", err)
+	}
+
+	return &payload.Data, nil
+}
+
+type ConfirmTokenData struct {
+	MailingListID gid.GID   `json:"m"`
+	Email         mail.Addr `json:"e"`
+}
+
+func newConfirmToken(secret string, mailingListID gid.GID, recipientEmail mail.Addr) (string, error) {
+	return statelesstoken.NewToken(
+		secret,
+		TokenTypeConfirm,
+		confirmTokenExpiry,
+		ConfirmTokenData{
+			MailingListID: mailingListID,
+			Email:         recipientEmail,
+		},
+	)
+}
+
+// ValidateConfirmToken validates a subscription confirmation token and returns
+// the embedded payload. Exported so the HTTP handler can use it.
+func ValidateConfirmToken(secret, tokenString string) (*ConfirmTokenData, error) {
+	payload, err := statelesstoken.ValidateToken[ConfirmTokenData](secret, TokenTypeConfirm, tokenString)
+	if err != nil {
+		return nil, fmt.Errorf("cannot validate confirm token: %w", err)
+	}
+
+	return &payload.Data, nil
+}