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 metrics
import (
"net/http"
"strconv"
"time"
"github.com/jkaninda/okapi"
"github.com/prometheus/client_golang/prometheus"
"github.com/prometheus/client_golang/prometheus/promhttp"
)
// labelStatus is the Prometheus label shared by the request, email, and
// message counters.
const labelStatus = "status"
var (
httpRequestsTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "posta_http_requests_total",
Help: "Total number of HTTP requests",
},
[]string{"method", "path", labelStatus},
)
httpRequestDuration = prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "posta_http_request_duration_seconds",
Help: "HTTP request duration in seconds",
Buckets: prometheus.DefBuckets,
},
[]string{"method", "path"},
)
emailsSentTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_emails_sent_total",
Help: "Total number of emails sent successfully",
},
)
emailsFailedTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_emails_failed_total",
Help: "Total number of emails that failed to send",
},
)
emailsQueueSize = prometheus.NewGauge(
prometheus.GaugeOpts{
Name: "posta_emails_queue_size",
Help: "Number of emails currently enqueued for delivery",
},
)
emailRetriesTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_email_retries_total",
Help: "Total number of email retry attempts",
},
)
webhookDeliveriesTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "posta_webhook_deliveries_total",
Help: "Total number of webhook delivery attempts by status",
},
[]string{labelStatus},
)
webhookDeliveryDuration = prometheus.NewHistogram(
prometheus.HistogramOpts{
Name: "posta_webhook_delivery_duration_seconds",
Help: "Duration of webhook delivery attempts in seconds",
Buckets: prometheus.DefBuckets,
},
)
bouncesTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "posta_bounces_total",
Help: "Total number of bounces recorded by type",
},
[]string{"type"},
)
suppressionsTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_suppressions_total",
Help: "Total number of email suppressions added",
},
)
inboundReceivedTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "posta_inbound_messages_received_total",
Help: "Total number of inbound messages accepted for processing, by source",
},
[]string{"source"},
)
messagesReceivedTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "posta_form_messages_received_total",
Help: "Total number of web form messages stored, by scan status",
},
[]string{labelStatus},
)
messageNotificationsTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_form_message_notifications_total",
Help: "Total number of web form message notifications delivered",
},
)
inboundForwardedTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_inbound_messages_forwarded_total",
Help: "Total number of inbound messages successfully dispatched to subscribers",
},
)
inboundFailedTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_inbound_messages_failed_total",
Help: "Total number of inbound messages that permanently failed to forward",
},
)
inboundRejectedTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "posta_inbound_messages_rejected_total",
Help: "Total number of inbound messages rejected at ingestion, by reason",
},
[]string{"reason"},
)
inboundBytesTotal = prometheus.NewCounter(
prometheus.CounterOpts{
Name: "posta_inbound_bytes_total",
Help: "Total bytes of raw inbound messages accepted",
},
)
inboundIngestDuration = prometheus.NewHistogram(
prometheus.HistogramOpts{
Name: "posta_inbound_ingest_duration_seconds",
Help: "Time spent ingesting an inbound message (parse + blob upload + DB write)",
Buckets: prometheus.DefBuckets,
},
)
activeWorkers = prometheus.NewGauge(
prometheus.GaugeOpts{
Name: "posta_active_workers",
Help: "Number of currently-connected Asynq workers (embedded + standalone)",
},
)
)
func init() {
prometheus.MustRegister(httpRequestsTotal)
prometheus.MustRegister(httpRequestDuration)
prometheus.MustRegister(emailsSentTotal)
prometheus.MustRegister(emailsFailedTotal)
prometheus.MustRegister(emailsQueueSize)
prometheus.MustRegister(emailRetriesTotal)
prometheus.MustRegister(webhookDeliveriesTotal)
prometheus.MustRegister(webhookDeliveryDuration)
prometheus.MustRegister(bouncesTotal)
prometheus.MustRegister(suppressionsTotal)
prometheus.MustRegister(inboundReceivedTotal)
prometheus.MustRegister(inboundForwardedTotal)
prometheus.MustRegister(inboundFailedTotal)
prometheus.MustRegister(inboundRejectedTotal)
prometheus.MustRegister(inboundBytesTotal)
prometheus.MustRegister(inboundIngestDuration)
prometheus.MustRegister(messagesReceivedTotal)
prometheus.MustRegister(messageNotificationsTotal)
prometheus.MustRegister(activeWorkers)
}
// IncrementEmailSent increments the emails sent counter.
func IncrementEmailSent() {
emailsSentTotal.Inc()
}
// IncrementEmailFailed increments the emails failed counter.
func IncrementEmailFailed() {
emailsFailedTotal.Inc()
}
// IncrementEmailQueued increments the in-flight queue-size gauge.
func IncrementEmailQueued() {
emailsQueueSize.Inc()
}
// DecrementEmailQueued decrements the in-flight queue-size gauge, called when
// a queued email finishes delivery (sent or permanently failed).
func DecrementEmailQueued() {
emailsQueueSize.Dec()
}
// IncrementEmailRetry increments the email retries counter.
func IncrementEmailRetry() {
emailRetriesTotal.Inc()
}
// IncrementWebhookDelivery increments the webhook delivery counter for the given status.
func IncrementWebhookDelivery(status string) {
webhookDeliveriesTotal.WithLabelValues(status).Inc()
}
// ObserveWebhookDeliveryDuration records a webhook delivery duration.
func ObserveWebhookDeliveryDuration(seconds float64) {
webhookDeliveryDuration.Observe(seconds)
}
// IncrementBounce increments the bounce counter for the given type (hard, soft, complaint).
func IncrementBounce(bounceType string) {
bouncesTotal.WithLabelValues(bounceType).Inc()
}
// IncrementSuppression increments the suppression counter.
func IncrementSuppression() {
suppressionsTotal.Inc()
}
// IncrementMessageReceived increments the web form message counter for the given scan status.
func IncrementMessageReceived(status string) {
messagesReceivedTotal.WithLabelValues(status).Inc()
}
// IncrementMessageNotification increments the web form notification counter.
func IncrementMessageNotification() {
messageNotificationsTotal.Inc()
}
// IncrementInboundReceived increments the inbound received counter for the given source.
func IncrementInboundReceived(source string) {
inboundReceivedTotal.WithLabelValues(source).Inc()
}
// IncrementInboundForwarded increments the inbound forwarded counter.
func IncrementInboundForwarded() {
inboundForwardedTotal.Inc()
}
// IncrementInboundFailed increments the permanently-failed inbound counter.
func IncrementInboundFailed() {
inboundFailedTotal.Inc()
}
// IncrementInboundRejected increments the rejected inbound counter for the given reason.
func IncrementInboundRejected(reason string) {
inboundRejectedTotal.WithLabelValues(reason).Inc()
}
// AddInboundBytes adds n bytes to the inbound bytes counter.
func AddInboundBytes(n int64) {
if n > 0 {
inboundBytesTotal.Add(float64(n))
}
}
// ObserveInboundIngestDuration records how long a single ingest took, in seconds.
func ObserveInboundIngestDuration(seconds float64) {
inboundIngestDuration.Observe(seconds)
}
// SetActiveWorkers updates the active worker gauge.
func SetActiveWorkers(n int) {
activeWorkers.Set(float64(n))
}
// PrometheusMiddleware records HTTP request metrics.
func PrometheusMiddleware() okapi.Middleware {
return func(c *okapi.Context) error {
start := time.Now()
err := c.Next()
duration := time.Since(start).Seconds()
method := c.Request().Method
path := c.Path()
status := strconv.Itoa(c.Response().StatusCode())
httpRequestsTotal.WithLabelValues(method, path, status).Inc()
httpRequestDuration.WithLabelValues(method, path).Observe(duration)
return err
}
}
// HTTPHandler returns the Prometheus handler for a plain net/http mux — the
// dedicated worker, which has no okapi router.
func HTTPHandler() http.Handler {
return promhttp.Handler()
}
// MetricsHandler returns the Prometheus metrics handler.
func MetricsHandler() okapi.HandlerFunc {
handler := promhttp.Handler()
return func(c *okapi.Context) error {
handler.ServeHTTP(c.Response().(http.ResponseWriter), c.Request())
return nil
}
}