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 handlers
import (
"context"
"crypto/sha256"
"crypto/subtle"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"io"
"mime"
"net/http"
"strings"
"time"
"github.com/goposta/posta/internal/models"
"github.com/goposta/posta/internal/services/eventbus"
"github.com/goposta/posta/internal/services/inbound"
"github.com/goposta/posta/internal/storage/blob"
"github.com/goposta/posta/internal/storage/repositories"
"github.com/goposta/posta/internal/worker"
"github.com/jkaninda/logger"
"github.com/jkaninda/okapi"
)
// InboundHandler serves inbound-email HTTP endpoints: the generic webhook ingest
// endpoint, list/get for authenticated users, and attachment downloads.
type InboundHandler struct {
svc *inbound.Service
repo *repositories.InboundEmailRepository
blobStore blob.Store
producer inbound.Enqueuer
bus *eventbus.EventBus
secret string
hmacKey []byte
}
func NewInboundHandler(
svc *inbound.Service,
repo *repositories.InboundEmailRepository,
blobStore blob.Store,
secret string,
hmacKey []byte,
) *InboundHandler {
return &InboundHandler{
svc: svc,
repo: repo,
blobStore: blobStore,
secret: secret,
hmacKey: hmacKey,
}
}
// SetEnqueuer configures the worker enqueuer for the retry endpoint.
func (h *InboundHandler) SetEnqueuer(eq inbound.Enqueuer) { h.producer = eq }
// SetEventBus configures the event bus used for SSE streaming.
func (h *InboundHandler) SetEventBus(b *eventbus.EventBus) { h.bus = b }
// Stream pushes email.inbound.received events to the authenticated user via SSE.
// Events from other users' inboxes are filtered out.
func (h *InboundHandler) Stream(c *okapi.Context) error {
if h.bus == nil {
return c.AbortNotFound("inbound stream not configured")
}
ctx := c.Request().Context()
scope := getScope(c)
ch, unsub := h.bus.Subscribe()
defer unsub()
msgCh := make(chan okapi.Message, 4)
msgCh <- okapi.Message{
Event: "system.info",
Data: okapi.M{
"user_id": scope.UserID,
"timestamp": time.Now().UTC().Format(time.RFC3339),
},
}
go func() {
defer close(msgCh)
for {
select {
case <-ctx.Done():
return
case evt, ok := <-ch:
if !ok {
return
}
if evt.Type != "email.inbound.received" && evt.Type != "email.inbound.forwarded" && evt.Type != "email.inbound.failed" {
continue
}
if evt.ActorID == nil || *evt.ActorID != scope.UserID {
continue
}
select {
case msgCh <- okapi.Message{Event: evt.Type, Data: evt}:
case <-ctx.Done():
return
}
}
}
}()
return c.SSEStreamWithOptions(ctx, msgCh, &okapi.StreamOptions{
Serializer: &okapi.JSONSerializer{},
PingInterval: 30 * time.Second,
})
}
// contentDisposition builds a safe Content-Disposition header. Non-ASCII filenames
// are RFC 5987 encoded; quotes and CR/LF are stripped from the fallback name.
func contentDisposition(filename string) string {
ascii := strings.Map(func(r rune) rune {
if r < 0x20 || r == 0x7f || r == '"' || r == '\\' || r > 0x7e {
return -1
}
return r
}, filename)
if ascii == "" {
ascii = "attachment"
}
return `attachment; filename="` + ascii + `"; filename*=UTF-8''` + urlPathEscape(filename)
}
// urlPathEscape percent-encodes a filename per RFC 5987 / 3986 unreserved.
func urlPathEscape(s string) string {
const unreserved = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.~"
var b strings.Builder
for _, c := range []byte(s) {
if strings.IndexByte(unreserved, c) >= 0 {
b.WriteByte(c)
} else {
b.WriteByte('%')
const hexd = "0123456789ABCDEF"
b.WriteByte(hexd[c>>4])
b.WriteByte(hexd[c&0x0f])
}
}
return b.String()
}
// constantTimeSecretEqual compares two secrets in constant time, including length.
func constantTimeSecretEqual(a, b string) bool {
if len(a) != len(b) {
// still run the compare to equalize timing
_ = subtle.ConstantTimeCompare([]byte(a), []byte(a))
return false
}
return subtle.ConstantTimeCompare([]byte(a), []byte(b)) == 1
}
// DedupFallbackHash derives a stable hash for messages without a Message-ID.
// Used by the webhook path to reject near-duplicate retries.
func DedupFallbackHash(sender string, recipients []string, subject string, size int64) string {
h := sha256.New()
h.Write([]byte(strings.ToLower(sender)))
h.Write([]byte{0})
for _, r := range recipients {
h.Write([]byte(strings.ToLower(r)))
h.Write([]byte{0})
}
h.Write([]byte(subject))
h.Write([]byte{0})
h.Write([]byte(mime.QEncoding.Encode("utf-8", "") + hex.EncodeToString([]byte{byte(size), byte(size >> 8), byte(size >> 16), byte(size >> 24)})))
return "fh-" + hex.EncodeToString(h.Sum(nil))[:24]
}
// InboundWebhookAttachment is the normalized attachment shape accepted on the
// generic webhook — content is base64-encoded. Providers (Mailgun/SendGrid/SES)
// can be adapted upstream to this shape.
type InboundWebhookAttachment struct {
Filename string `json:"filename"`
ContentType string `json:"content_type"`
Content string `json:"content" doc:"Base64-encoded content"`
}
// InboundWebhookRequest is the normalized inbound-email payload accepted on the
// public webhook endpoint.
type InboundWebhookRequest struct {
PostaInboundSecret string `header:"X-Posta-Inbound-Secret" required:"true"`
Body struct {
From string `json:"from" required:"true"`
To []string `json:"to" required:"true"`
Subject string `json:"subject"`
Text string `json:"text"`
HTML string `json:"html"`
Headers map[string]string `json:"headers"`
MessageID string `json:"message_id"`
SpamScore *float64 `json:"spam_score,omitempty"`
Attachments []InboundWebhookAttachment `json:"attachments"`
Raw string `json:"raw" doc:"Optional base64-encoded raw RFC 5322 message"`
} `json:"body"`
}
type InboundWebhookResponse struct {
Accepted bool `json:"accepted"`
InboundID string `json:"inbound_id,omitempty"`
Status string `json:"status"`
}
// Receive accepts a normalized inbound email from an external MX provider.
// Auth is a shared secret provided via X-Posta-Inbound-Secret header.
func (h *InboundHandler) Receive(c *okapi.Context, req *InboundWebhookRequest) error {
if h.secret == "" {
return c.AbortForbidden("inbound webhook is not configured")
}
if !constantTimeSecretEqual(req.PostaInboundSecret, h.secret) {
return c.AbortUnauthorized("invalid inbound secret")
}
parsed := &inbound.ParsedEmail{
MessageID: strings.Trim(req.Body.MessageID, "<>"),
From: req.Body.From,
To: req.Body.To,
Subject: req.Body.Subject,
TextBody: req.Body.Text,
HTMLBody: req.Body.HTML,
Headers: req.Body.Headers,
Date: time.Now().UTC(),
}
if req.Body.Raw != "" {
if raw, err := base64.StdEncoding.DecodeString(req.Body.Raw); err == nil {
parsed.Raw = raw
}
}
for _, a := range req.Body.Attachments {
decoded, err := base64.StdEncoding.DecodeString(a.Content)
if err != nil {
return c.AbortBadRequest("invalid base64 in attachment " + a.Filename)
}
parsed.Attachments = append(parsed.Attachments, inbound.ParsedAttachment{
Filename: a.Filename,
ContentType: a.ContentType,
Content: decoded,
Size: int64(len(decoded)),
})
}
ctx, cancel := context.WithTimeout(c.Request().Context(), 30*time.Second)
defer cancel()
rec, err := h.svc.Ingest(ctx, parsed, models.InboundSourceWebhook)
switch {
case err == nil:
return c.JSON(http.StatusAccepted, InboundWebhookResponse{Accepted: true, InboundID: rec.UUID, Status: "received"})
case errors.Is(err, inbound.ErrDuplicate):
return c.JSON(http.StatusOK, InboundWebhookResponse{Accepted: true, InboundID: rec.UUID, Status: "duplicate"})
case errors.Is(err, inbound.ErrUnverifiedDomain):
return c.AbortForbidden("recipient domain is not verified")
case errors.Is(err, inbound.ErrSizeExceeded), errors.Is(err, inbound.ErrAttachmentTooLarge):
return c.JSON(http.StatusRequestEntityTooLarge, InboundWebhookResponse{Accepted: false, Status: "too_large"})
case errors.Is(err, inbound.ErrSenderSuppressed):
uuid := ""
if rec != nil {
uuid = rec.UUID
}
return c.JSON(http.StatusAccepted, InboundWebhookResponse{Accepted: true, InboundID: uuid, Status: "suppressed"})
default:
return c.AbortInternalServerError("failed to ingest inbound email", err)
}
}
// InboundListRequest extends ListRequest with filter query params.
type InboundListRequest struct {
Page int `query:"page" default:"0"`
Size int `query:"size" default:"20"`
Status string `query:"status" doc:"Filter by status: received|forwarded|failed|rejected"`
Source string `query:"source" doc:"Filter by source: smtp|webhook"`
Sender string `query:"sender" doc:"Filter by sender address (substring, case-insensitive)"`
Q string `query:"q" doc:"Full-text search on subject"`
}
// List returns inbound emails for the current scope, with optional filters.
func (h *InboundHandler) List(c *okapi.Context, req *InboundListRequest) error {
page, size, offset := normalizePageParams(req.Page, req.Size)
items, total, err := h.repo.FindByScopeFiltered(getScope(c), repositories.InboundFilter{
Status: req.Status,
Source: req.Source,
Sender: req.Sender,
Query: req.Q,
}, size, offset)
if err != nil {
return c.AbortInternalServerError("failed to list inbound emails", err)
}
return paginated(c, items, total, page, size)
}
// Delete removes an inbound email by UUID (scope-checked) and cleans up blob-stored content.
func (h *InboundHandler) Delete(c *okapi.Context, req *GetEmailRequest) error {
rec, err := h.repo.FindByUUID(req.ID)
if err != nil {
return c.AbortNotFound("inbound email not found")
}
if !ownsResource(c, rec.UserID, rec.WorkspaceID) {
return c.AbortNotFound("inbound email not found")
}
// Best-effort blob cleanup.
if h.blobStore != nil {
if rec.AttachmentsJSON != "" {
var atts []models.InboundAttachmentMeta
if err := json.Unmarshal([]byte(rec.AttachmentsJSON), &atts); err == nil {
for _, a := range atts {
if a.StorageKey != "" {
_ = h.blobStore.Delete(c.Request().Context(), a.StorageKey)
}
}
}
}
if rec.RawStorageKey != "" {
_ = h.blobStore.Delete(c.Request().Context(), rec.RawStorageKey)
}
}
if err := h.repo.Delete(rec.ID); err != nil {
return c.AbortInternalServerError("failed to delete inbound email", err)
}
return noContent(c)
}
// Retry re-enqueues an inbound email for another attempt. Quarantined records
// (those that failed during parsing) are routed back through inbound:parse so
// the operator can re-run the MIME pipeline after a fix is deployed; failed
// or stuck records (parsed but webhook delivery exhausted) go back through
// inbound:process for re-dispatch.
func (h *InboundHandler) Retry(c *okapi.Context, req *GetEmailRequest) error {
if h.producer == nil {
return c.AbortForbidden("inbound retry requires an async worker")
}
rec, err := h.repo.FindByUUID(req.ID)
if err != nil {
return c.AbortNotFound("inbound email not found")
}
if !ownsResource(c, rec.UserID, rec.WorkspaceID) {
return c.AbortNotFound("inbound email not found")
}
switch rec.Status {
case models.InboundStatusQuarantined:
rec.Status = models.InboundStatusReceived
rec.ErrorMessage = ""
if err := h.repo.Update(rec); err != nil {
return c.AbortInternalServerError("failed to update inbound email", err)
}
if err := h.producer.EnqueueInboundParse(rec.ID); err != nil {
return c.AbortInternalServerError("failed to enqueue inbound parse task", err)
}
case models.InboundStatusFailed, models.InboundStatusReceived:
rec.Status = models.InboundStatusReceived
rec.ErrorMessage = ""
if err := h.repo.Update(rec); err != nil {
return c.AbortInternalServerError("failed to update inbound email", err)
}
if err := h.producer.EnqueueInboundProcess(rec.ID); err != nil {
return c.AbortInternalServerError("failed to enqueue inbound task", err)
}
default:
return c.AbortBadRequest("only failed, quarantined, or stuck received messages can be retried")
}
return ok(c, map[string]string{"id": rec.UUID, "status": string(rec.Status)})
}
// DownloadAttachmentAuthed streams an inbound attachment to an authenticated user
// who owns the record — no signed token required.
func (h *InboundHandler) DownloadAttachmentAuthed(c *okapi.Context, req *InboundAttachmentOwnedRequest) error {
rec, err := h.repo.FindByUUID(req.UUID)
if err != nil {
return c.AbortNotFound("inbound email not found")
}
if !ownsResource(c, rec.UserID, rec.WorkspaceID) {
return c.AbortNotFound("inbound email not found")
}
return h.streamAttachment(c, rec, req.Index)
}
// InboundAttachmentOwnedRequest is the path-params-only variant used by authed users.
type InboundAttachmentOwnedRequest struct {
UUID string `param:"id" doc:"Inbound email UUID"`
Index int `param:"idx" doc:"Zero-based attachment index"`
}
// GetRaw streams the raw RFC 5322 message bytes (if stored).
func (h *InboundHandler) GetRaw(c *okapi.Context, req *GetEmailRequest) error {
rec, err := h.repo.FindByUUID(req.ID)
if err != nil {
return c.AbortNotFound("inbound email not found")
}
if !ownsResource(c, rec.UserID, rec.WorkspaceID) {
return c.AbortNotFound("inbound email not found")
}
if rec.RawStorageKey == "" || h.blobStore == nil {
return c.AbortNotFound("raw message not available")
}
rc, err := h.blobStore.Get(c.Request().Context(), rec.RawStorageKey)
if err != nil {
return c.AbortInternalServerError("failed to fetch raw message", err)
}
defer func() { _ = rc.Close() }()
c.ResponseWriter().Header().Set("Content-Type", "message/rfc822")
c.ResponseWriter().Header().Set("Content-Disposition", contentDisposition(rec.UUID+".eml"))
c.ResponseWriter().WriteHeader(http.StatusOK)
if _, err := io.Copy(c.ResponseWriter(), rc); err != nil {
logger.Warn("inbound raw stream failed", "uuid", rec.UUID, "error", err)
}
return nil
}
// streamAttachment is the shared body for both signed and authed attachment endpoints.
func (h *InboundHandler) streamAttachment(c *okapi.Context, rec *models.InboundEmail, idx int) error {
var atts []models.InboundAttachmentMeta
if rec.AttachmentsJSON != "" {
if err := json.Unmarshal([]byte(rec.AttachmentsJSON), &atts); err != nil {
return c.AbortInternalServerError("failed to decode attachment metadata", err)
}
}
if idx < 0 || idx >= len(atts) {
return c.AbortNotFound("attachment not found")
}
meta := atts[idx]
c.ResponseWriter().Header().Set("Content-Type", meta.ContentType)
if meta.Filename != "" {
c.ResponseWriter().Header().Set("Content-Disposition", contentDisposition(meta.Filename))
}
if meta.StorageKey != "" && h.blobStore != nil {
rc, err := h.blobStore.Get(c.Request().Context(), meta.StorageKey)
if err != nil {
return c.AbortInternalServerError("failed to fetch attachment", err)
}
defer func() { _ = rc.Close() }()
c.ResponseWriter().WriteHeader(http.StatusOK)
if _, err := io.Copy(c.ResponseWriter(), rc); err != nil {
// Response already committed — log and return nil since headers are flushed.
logger.Warn("inbound attachment stream failed", "uuid", rec.UUID, "error", err)
}
return nil
}
if meta.Content != "" {
raw, err := base64.StdEncoding.DecodeString(meta.Content)
if err != nil {
return c.AbortInternalServerError("failed to decode inline attachment", err)
}
c.ResponseWriter().WriteHeader(http.StatusOK)
_, _ = c.ResponseWriter().Write(raw)
return nil
}
return c.AbortNotFound("attachment content unavailable")
}
// Get returns a single inbound email by UUID (scope-checked).
func (h *InboundHandler) Get(c *okapi.Context, req *GetEmailRequest) error {
rec, err := h.repo.FindByUUID(req.ID)
if err != nil {
return c.AbortNotFound("inbound email not found")
}
if !ownsResource(c, rec.UserID, rec.WorkspaceID) {
return c.AbortNotFound("inbound email not found")
}
return ok(c, rec)
}
// InboundAttachmentRequest identifies a specific attachment on an inbound email.
type InboundAttachmentRequest struct {
UUID string `param:"uuid"`
Index int `param:"idx"`
Token string `query:"t"`
}
// ServeAttachment streams an inbound attachment from blob storage after validating
// the HMAC-signed token. Used by webhook consumers to fetch bytes asynchronously.
func (h *InboundHandler) ServeAttachment(c *okapi.Context, req *InboundAttachmentRequest) error {
if req.Token == "" || !worker.VerifyInboundAttachmentToken(h.hmacKey, req.UUID, req.Index, req.Token) {
return c.AbortUnauthorized("invalid or missing token")
}
rec, err := h.repo.FindByUUID(req.UUID)
if err != nil {
return c.AbortNotFound("inbound email not found")
}
var atts []models.InboundAttachmentMeta
if rec.AttachmentsJSON != "" {
if err := json.Unmarshal([]byte(rec.AttachmentsJSON), &atts); err != nil {
return c.AbortInternalServerError("failed to decode attachment metadata", err)
}
}
if req.Index < 0 || req.Index >= len(atts) {
return c.AbortNotFound("attachment not found")
}
meta := atts[req.Index]
c.ResponseWriter().Header().Set("Content-Type", meta.ContentType)
if meta.Filename != "" {
c.ResponseWriter().Header().Set("Content-Disposition", contentDisposition(meta.Filename))
}
if meta.StorageKey != "" && h.blobStore != nil {
rc, err := h.blobStore.Get(c.Request().Context(), meta.StorageKey)
if err != nil {
return c.AbortInternalServerError("failed to fetch attachment", err)
}
defer func() { _ = rc.Close() }()
c.ResponseWriter().WriteHeader(http.StatusOK)
if _, err := io.Copy(c.ResponseWriter(), rc); err != nil {
logger.Warn("inbound attachment stream failed", "uuid", req.UUID, "error", err)
}
return nil
}
if meta.Content != "" {
raw, err := base64.StdEncoding.DecodeString(meta.Content)
if err != nil {
return c.AbortInternalServerError("failed to decode inline attachment", err)
}
c.ResponseWriter().WriteHeader(http.StatusOK)
_, _ = c.ResponseWriter().Write(raw)
return nil
}
return c.AbortNotFound("attachment content unavailable")
}