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 verifier checks whether an email address is valid/deliverable without
// sending to it. It runs cheap-to-expensive checks (syntax, suppression/bounce
// history, disposable/role detection, MX lookup) and caches the intrinsic result
// in Redis so the same address and domain are not re-checked on every call.
//
// Note: the MVP does not perform an SMTP RCPT probe, so mailbox existence is not
// confirmed; checks.smtp is reported as "skipped".
package verifier
import (
"context"
"encoding/json"
"errors"
"fmt"
"net"
"net/mail"
"strings"
"time"
"github.com/goposta/posta/internal/storage/repositories"
"github.com/redis/go-redis/v9"
)
// ErrRateLimited is returned by Verify when the per-user hourly limit is hit.
var ErrRateLimited = errors.New("verification rate limit exceeded")
// Status is the overall verdict for an address.
type Status string
const (
StatusValid Status = "valid" // syntax ok + domain accepts mail (mailbox not probed)
StatusInvalid Status = "invalid" // definitely undeliverable
StatusRisky Status = "risky" // deliverable but discouraged (role account)
StatusDisposable Status = "disposable" // throwaway provider
StatusUnknown Status = "unknown" // could not determine (e.g. DNS error)
)
// Checks records which individual checks passed.
type Checks struct {
Syntax bool `json:"syntax"`
MX bool `json:"mx"`
Disposable bool `json:"disposable"`
RoleAccount bool `json:"role_account"`
SMTP string `json:"smtp"` // always "skipped"; no SMTP probe is performed
}
// Result is the verification outcome returned to the caller. The intrinsic
// fields (everything except Suppressed/PreviouslyBounced/Cached) are what gets
// cached in Redis; the per-tenant flags are layered on per request.
type Result struct {
Email string `json:"email"`
Status Status `json:"status" enum:"valid,invalid,risky,disposable,unknown"`
Score int `json:"score"`
Checks Checks `json:"checks"`
Reason string `json:"reason,omitempty"`
MailboxVerified bool `json:"mailbox_verified"`
Suppressed bool `json:"suppressed"`
PreviouslyBounced bool `json:"previously_bounced"`
Cached bool `json:"cached"`
CheckedAt time.Time `json:"checked_at"`
}
// Options configures a Service. Durations and limits come from app config.
type Options struct {
Enabled bool
AddrTTL time.Duration
MXTTL time.Duration
RateHourly int // per-user hourly cap; 0 disables rate limiting
}
// Service verifies email addresses and caches results in Redis.
type Service struct {
client *redis.Client
suppressionRepo *repositories.SuppressionRepository
bounceRepo *repositories.BounceRepository
opts Options
resolver *net.Resolver // injectable for tests; nil uses the default
}
// NewService builds a verifier. suppressionRepo/bounceRepo may be nil (the
// per-tenant overlay is then skipped); client must be non-nil for caching.
func NewService(client *redis.Client, suppressionRepo *repositories.SuppressionRepository, bounceRepo *repositories.BounceRepository, opts Options) *Service {
return &Service{
client: client,
suppressionRepo: suppressionRepo,
bounceRepo: bounceRepo,
opts: opts,
resolver: net.DefaultResolver,
}
}
// Enabled reports whether verification is turned on.
func (s *Service) Enabled() bool { return s.opts.Enabled }
// Verify checks an address. fresh=true bypasses the Redis cache. The returned
// Result always reflects the current tenant's suppression/bounce history.
func (s *Service) Verify(ctx context.Context, scope repositories.ResourceScope, rawEmail string, fresh bool) (*Result, error) {
email := strings.ToLower(strings.TrimSpace(rawEmail))
// Syntax. A malformed address is conclusively invalid.
addr, err := mail.ParseAddress(email)
if err != nil {
r := baseResult(email)
r.Status = StatusInvalid
r.Reason = "invalid syntax"
return r, nil
}
email = strings.ToLower(addr.Address)
// Per-user rate limit (fail-open on Redis errors).
if s.opts.RateHourly > 0 {
if err := s.checkRate(ctx, scope.UserID); err != nil {
return nil, err
}
}
// Per-tenant history overlay (no network). Suppressed or previously
// hard-bounced addresses are conclusively bad for this tenant.
suppressed, bounced := s.tenantOverlay(scope, email)
if suppressed || bounced {
r := baseResult(email)
r.Checks.Syntax = true
r.Status = StatusInvalid
r.Score = 0
r.Suppressed = suppressed
r.PreviouslyBounced = bounced
if suppressed {
r.Reason = "address is on the suppression list"
} else {
r.Reason = "address previously hard-bounced"
}
return r, nil
}
// Redis cache for the intrinsic result.
if !fresh {
if cached := s.getCache(ctx, email); cached != nil {
cached.Cached = true
cached.Suppressed = suppressed
cached.PreviouslyBounced = bounced
return cached, nil
}
}
// Compute the intrinsic result (disposable/role/MX) and cache it.
r := s.compute(ctx, email)
s.setCache(ctx, email, r)
r.Suppressed = suppressed
r.PreviouslyBounced = bounced
return r, nil
}
// compute runs the intrinsic checks for a syntactically valid address.
func (s *Service) compute(ctx context.Context, email string) *Result {
r := baseResult(email)
r.Checks.Syntax = true
at := strings.LastIndex(email, "@")
local, domain := email[:at], email[at+1:]
disposable := isDisposable(domain)
role := isRoleAccount(local)
r.Checks.Disposable = disposable
r.Checks.RoleAccount = role
// Disposable domains are disqualified without a DNS lookup.
if disposable {
r.Status, r.Score, r.Reason = decide(true, true, role, false)
return r
}
hosts := s.mxHosts(ctx, domain)
r.Checks.MX = len(hosts) > 0
r.Status, r.Score, r.Reason = decide(true, false, role, len(hosts) > 0)
return r
}
// decide encodes the verdict precedence as a pure function so it is easy to test.
func decide(syntaxOK, disposable, roleAccount, hasMX bool) (Status, int, string) {
switch {
case !syntaxOK:
return StatusInvalid, 0, "invalid syntax"
case disposable:
return StatusDisposable, 10, "disposable email provider"
case !hasMX:
return StatusInvalid, 0, "domain has no mail exchanger (MX/A) records"
case roleAccount:
return StatusRisky, 60, "role-based address"
default:
return StatusValid, 90, ""
}
}
// tenantOverlay returns the current tenant's suppression/bounce status.
func (s *Service) tenantOverlay(scope repositories.ResourceScope, email string) (suppressed, bounced bool) {
if s.suppressionRepo != nil {
if ok, err := s.suppressionRepo.IsSuppressed(scope, email); err == nil {
suppressed = ok
}
}
if s.bounceRepo != nil {
if n, err := s.bounceRepo.CountHardBouncesByRecipient(scope.UserID, email); err == nil && n > 0 {
bounced = true
}
}
return suppressed, bounced
}
// mxHosts returns the domain's mail exchangers (or the domain itself when only
// an A/AAAA record exists — an implicit MX per RFC 5321 §5.1), caching the
// answer per domain in Redis. An empty slice means the domain cannot receive
// mail. The cached sentinel "none" distinguishes a negative result from a miss.
func (s *Service) mxHosts(ctx context.Context, domain string) []string {
key := mxKey(domain)
if s.client != nil {
if v, err := s.client.Get(ctx, key).Result(); err == nil {
if v == "" || v == "none" {
return nil
}
return strings.Split(v, ",")
}
}
hosts := s.lookupMX(ctx, domain)
if s.client != nil {
val := "none"
if len(hosts) > 0 {
val = strings.Join(hosts, ",")
}
s.client.Set(ctx, key, val, s.opts.MXTTL)
}
return hosts
}
func (s *Service) lookupMX(ctx context.Context, domain string) []string {
lookupCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
resolver := s.resolver
if resolver == nil {
resolver = net.DefaultResolver
}
if mxs, err := resolver.LookupMX(lookupCtx, domain); err == nil && len(mxs) > 0 {
hosts := make([]string, 0, len(mxs))
for _, mx := range mxs {
hosts = append(hosts, mx.Host)
}
return hosts
}
// Fallback: a domain with an A/AAAA record can still receive mail.
if addrs, err := resolver.LookupHost(lookupCtx, domain); err == nil && len(addrs) > 0 {
return []string{domain}
}
return nil
}
// checkRate increments a per-user hourly counter; fails open on Redis errors.
func (s *Service) checkRate(ctx context.Context, userID uint) error {
if s.client == nil {
return nil
}
key := fmt.Sprintf("verify:rl:hour:%d:%s", userID, time.Now().Format("2006010215"))
n, err := s.client.Incr(ctx, key).Result()
if err != nil {
return nil
}
if n == 1 {
s.client.Expire(ctx, key, time.Hour)
}
if n > int64(s.opts.RateHourly) {
return ErrRateLimited
}
return nil
}
func (s *Service) getCache(ctx context.Context, email string) *Result {
if s.client == nil {
return nil
}
val, err := s.client.Get(ctx, addrKey(email)).Result()
if err != nil {
return nil
}
var r Result
if json.Unmarshal([]byte(val), &r) != nil {
return nil
}
return &r
}
func (s *Service) setCache(ctx context.Context, email string, r *Result) {
if s.client == nil {
return
}
b, err := json.Marshal(r)
if err != nil {
return
}
s.client.Set(ctx, addrKey(email), b, s.opts.AddrTTL)
}
func baseResult(email string) *Result {
return &Result{
Email: email,
Status: StatusUnknown,
Checks: Checks{SMTP: "skipped"},
CheckedAt: time.Now().UTC(),
}
}
func addrKey(email string) string { return "verify:addr:" + email }
func mxKey(domain string) string { return "verify:mx:" + strings.ToLower(domain) }