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.
Go email-relayemail-routinghttp-to-smtpmail-deliverymailchimp-alternativemailgun-alternativemailsendermailservermailtemplatemailtestpostmark-alternativesend-emailsendgrid-alternativesendmailtransactional-emailtransactional-outbox
// 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 tracking
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"errors"
"fmt"
"regexp"
"strconv"
"strings"
"time"
"github.com/goposta/posta/internal/storage/repositories"
)
// defaultWebViewTTL bounds how long a hosted "view in browser" link stays valid.
// A web-view link exposes full message content, so unlike unsubscribe tokens it
// carries an expiry.
const defaultWebViewTTL = 90 * 24 * time.Hour
// Service handles link rewriting and pixel injection for campaign emails.
type Service struct {
repo *repositories.TrackingRepository
baseURL string // e.g. "https://posta.example.com"
hmacKey []byte
}
func NewService(repo *repositories.TrackingRepository, baseURL string, hmacKey []byte) *Service {
return &Service{repo: repo, baseURL: strings.TrimRight(baseURL, "/"), hmacKey: hmacKey}
}
// (?i) makes the href match case-insensitive so HREF="…" still matches.
var linkRegex = regexp.MustCompile(`(?i)href\s*=\s*["'](https?://[^"']+)["']`)
// ProcessHTML rewrites links for click tracking and injects the open tracking pixel.
func (s *Service) ProcessHTML(html string, campaignID uint, messageID uint) string {
if html == "" {
return html
}
trackingPrefix := s.baseURL + "/t/"
// Rewrite links for click tracking
html = linkRegex.ReplaceAllStringFunc(html, func(match string) string {
sub := linkRegex.FindStringSubmatch(match)
if len(sub) < 2 {
return match
}
originalURL := sub[1]
// Skip URLs that are already our own tracking endpoints. The previous
// `Contains("/t/")` check accidentally skipped any legitimate link
// whose path segment contained "/t/" (e.g. blog posts).
if strings.HasPrefix(originalURL, trackingPrefix) {
return match
}
// Skip non-http schemes that slipped through the regex bound (defense-in-depth).
lower := strings.ToLower(originalURL)
if strings.HasPrefix(lower, "mailto:") || strings.HasPrefix(lower, "tel:") {
return match
}
hash := hashLink(campaignID, originalURL)
_, err := s.repo.FindOrCreateLink(campaignID, originalURL, hash)
if err != nil {
return match
}
trackedURL := s.ClickURL(messageID, hash)
return strings.Replace(match, originalURL, trackedURL, 1)
})
// Inject open tracking pixel before </body>. The URL is HMAC-signed so
// metrics can't be inflated by a third party hitting the predictable
// /t/o/<msg_id> path.
pixel := fmt.Sprintf(`<img src="%s" width="1" height="1" alt="" style="display:none" />`, s.OpenURL(messageID))
if strings.Contains(html, "</body>") {
html = strings.Replace(html, "</body>", pixel+"</body>", 1)
} else {
html += pixel
}
return html
}
// OpenURL builds a signed open-tracking pixel URL.
func (s *Service) OpenURL(messageID uint) string {
return fmt.Sprintf("%s/t/o/%d.gif?sig=%s", s.baseURL, messageID, s.signOpen(messageID))
}
// ClickURL builds a signed click-tracking redirect URL.
func (s *Service) ClickURL(messageID uint, hash string) string {
return fmt.Sprintf("%s/t/c/%d/%s?sig=%s", s.baseURL, messageID, hash, s.signClick(messageID, hash))
}
// VerifyOpenSig checks an open-tracking signature.
func (s *Service) VerifyOpenSig(messageID uint, sig string) bool {
return hmac.Equal([]byte(sig), []byte(s.signOpen(messageID)))
}
// VerifyClickSig checks a click-tracking signature.
func (s *Service) VerifyClickSig(messageID uint, hash, sig string) bool {
return hmac.Equal([]byte(sig), []byte(s.signClick(messageID, hash)))
}
func (s *Service) signOpen(messageID uint) string {
mac := hmac.New(sha256.New, s.hmacKey)
_, _ = fmt.Fprintf(mac, "open:%d", messageID)
return base64.RawURLEncoding.EncodeToString(mac.Sum(nil)[:16])
}
func (s *Service) signClick(messageID uint, hash string) string {
mac := hmac.New(sha256.New, s.hmacKey)
_, _ = fmt.Fprintf(mac, "click:%d:%s", messageID, hash)
return base64.RawURLEncoding.EncodeToString(mac.Sum(nil)[:16])
}
// SignUnsubscribeToken creates an HMAC-signed token encoding the message ID.
func (s *Service) SignUnsubscribeToken(messageID uint) string {
payload := strconv.FormatUint(uint64(messageID), 10)
mac := hmac.New(sha256.New, s.hmacKey)
mac.Write([]byte(payload))
sig := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
return base64.RawURLEncoding.EncodeToString([]byte(payload)) + "." + sig
}
// VerifyUnsubscribeToken verifies the HMAC token and returns the message ID.
func (s *Service) VerifyUnsubscribeToken(token string) (uint, error) {
parts := strings.SplitN(token, ".", 2)
if len(parts) != 2 {
return 0, errors.New("invalid token format")
}
payloadBytes, err := base64.RawURLEncoding.DecodeString(parts[0])
if err != nil {
return 0, errors.New("invalid token encoding")
}
payload := string(payloadBytes)
mac := hmac.New(sha256.New, s.hmacKey)
mac.Write(payloadBytes)
expectedSig := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(parts[1]), []byte(expectedSig)) {
return 0, errors.New("invalid token signature")
}
id, err := strconv.ParseUint(payload, 10, 64)
if err != nil {
return 0, errors.New("invalid message ID in token")
}
return uint(id), nil
}
// UnsubscribeURL generates the unsubscribe URL for a campaign message.
func (s *Service) UnsubscribeURL(messageID uint) string {
return fmt.Sprintf("%s/t/u/%s", s.baseURL, s.SignUnsubscribeToken(messageID))
}
// SignTxUnsubscribeToken creates an HMAC-signed token encoding a transactional
// email ID. The "tx:" prefix distinguishes it from campaign-message tokens so
// the two token kinds can't be confused or replayed against the wrong handler.
func (s *Service) SignTxUnsubscribeToken(emailID uint) string {
payload := "tx:" + strconv.FormatUint(uint64(emailID), 10)
mac := hmac.New(sha256.New, s.hmacKey)
mac.Write([]byte(payload))
sig := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
return base64.RawURLEncoding.EncodeToString([]byte(payload)) + "." + sig
}
// VerifyTxUnsubscribeToken verifies a transactional unsubscribe
func (s *Service) VerifyTxUnsubscribeToken(token string) (uint, error) {
parts := strings.SplitN(token, ".", 2)
if len(parts) != 2 {
return 0, errors.New("invalid token format")
}
payloadBytes, err := base64.RawURLEncoding.DecodeString(parts[0])
if err != nil {
return 0, errors.New("invalid token encoding")
}
mac := hmac.New(sha256.New, s.hmacKey)
mac.Write(payloadBytes)
expectedSig := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(parts[1]), []byte(expectedSig)) {
return 0, errors.New("invalid token signature")
}
payload := string(payloadBytes)
if !strings.HasPrefix(payload, "tx:") {
return 0, errors.New("wrong token kind")
}
id, err := strconv.ParseUint(payload[3:], 10, 64)
if err != nil {
return 0, errors.New("invalid email ID in token")
}
return uint(id), nil
}
// TxUnsubscribeURL returns the public one-click unsubscribe URL for a
// transactional email. Suitable for RFC 8058 List-Unsubscribe-Post headers.
func (s *Service) TxUnsubscribeURL(emailID uint) string {
return fmt.Sprintf("%s/t/u/tx/%s", s.baseURL, s.SignTxUnsubscribeToken(emailID))
}
// SignWebViewToken creates an HMAC-signed token for the hosted "view in browser"
// page. The payload encodes the opaque Email UUID (non-enumerable) plus an expiry,
// and a "view:" prefix binds the token kind so it can't be replayed against the
// unsubscribe handlers.
func (s *Service) SignWebViewToken(emailUUID string, ttl time.Duration) string {
exp := time.Now().Add(ttl).Unix()
payload := fmt.Sprintf("view:%s:%d", emailUUID, exp)
mac := hmac.New(sha256.New, s.hmacKey)
mac.Write([]byte(payload))
sig := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
return base64.RawURLEncoding.EncodeToString([]byte(payload)) + "." + sig
}
// VerifyWebViewToken verifies the HMAC token, checks the expiry, and returns the
// Email UUID it encodes.
func (s *Service) VerifyWebViewToken(token string) (string, error) {
parts := strings.SplitN(token, ".", 2)
if len(parts) != 2 {
return "", errors.New("invalid token format")
}
payloadBytes, err := base64.RawURLEncoding.DecodeString(parts[0])
if err != nil {
return "", errors.New("invalid token encoding")
}
mac := hmac.New(sha256.New, s.hmacKey)
mac.Write(payloadBytes)
expectedSig := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(parts[1]), []byte(expectedSig)) {
return "", errors.New("invalid token signature")
}
payload := string(payloadBytes)
if !strings.HasPrefix(payload, "view:") {
return "", errors.New("wrong token kind")
}
rest := payload[len("view:"):]
sep := strings.LastIndex(rest, ":")
if sep <= 0 {
return "", errors.New("invalid token payload")
}
emailUUID := rest[:sep]
exp, err := strconv.ParseInt(rest[sep+1:], 10, 64)
if err != nil {
return "", errors.New("invalid token expiry")
}
if time.Now().Unix() > exp {
return "", errors.New("token expired")
}
return emailUUID, nil
}
// WebViewURL returns the public "view in browser" URL for a transactional or
// campaign email, keyed by its opaque UUID. Returns "" for an empty UUID.
func (s *Service) WebViewURL(emailUUID string) string {
if emailUUID == "" {
return ""
}
return fmt.Sprintf("%s/t/v/%s", s.baseURL, s.SignWebViewToken(emailUUID, defaultWebViewTTL))
}
// hashLink generates a deterministic hash for a campaign + URL combination.
func hashLink(campaignID uint, url string) string {
h := sha256.New()
_, _ = fmt.Fprintf(h, "%d:%s", campaignID, url)
return hex.EncodeToString(h.Sum(nil))[:16]
}