Skip to content

armgit / posta

Public Imported from GitHub
0

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.

feat(openapi): add OpenAPI webhooks (events Posta POSTs to subscribers)

Jonas Kanindad66383185918
diff --git a/internal/dto/webhook_events.go b/internal/dto/webhook_events.go
new file mode 100644
index 0000000..c61a4d6
--- /dev/null
+++ b/internal/dto/webhook_events.go
@@ -0,0 +1,78 @@
+/*
+ * Copyright 2026 Jonas Kaninda
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package dto
+
+// This file defines documentation-only payload shapes for the webhooks Posta
+// POSTs to subscriber URLs.
+type WebhookEvent struct {
+ Event string `json:"event"`
+ EmailID string `json:"email_id"`
+ Timestamp string `json:"timestamp"`
+}
+
+// CampaignWebhookEvent is the payload for campaign lifecycle events
+// (campaign.started, campaign.completed).
+type CampaignWebhookEvent struct {
+ Event string `json:"event"`
+ CampaignID uint `json:"campaign_id"`
+ Name string `json:"name"`
+ Timestamp string `json:"timestamp"`
+}
+
+// ComplaintWebhookEvent is the payload for email.complained.
+type ComplaintWebhookEvent struct {
+ Event string `json:"event"`
+ EmailUUID string `json:"email_uuid"`
+ Email string `json:"email"`
+ Timestamp string `json:"timestamp"`
+}
+
+// UnsubscribeWebhookEvent is the payload for email.unsubscribed.
+type UnsubscribeWebhookEvent struct {
+ Event string `json:"event"`
+ EmailUUID string `json:"email_uuid"`
+ Email string `json:"email"`
+ ListID *uint `json:"list_id,omitempty"`
+ Timestamp string `json:"timestamp"`
+}
+
+// InboundWebhookEvent is the payload for email.inbound.
+type InboundWebhookEvent struct {
+ Event string `json:"event"`
+ Timestamp string `json:"timestamp"`
+ InboundID string `json:"inbound_id"`
+ From string `json:"from"`
+ To []string `json:"to"`
+ Subject string `json:"subject"`
+ TextBody string `json:"text_body,omitempty"`
+ HTMLBody string `json:"html_body,omitempty"`
+ Headers map[string]string `json:"headers,omitempty"`
+ Attachments []InboundWebhookAttachment `json:"attachments,omitempty"`
+ Size int64 `json:"size"`
+ MessageID string `json:"message_id,omitempty"`
+ Source string `json:"source"`
+ ReceivedAt string `json:"received_at"`
+}
+
+// InboundWebhookAttachment describes an attachment in an InboundWebhookEvent.
+type InboundWebhookAttachment struct {
+ Filename string `json:"filename"`
+ ContentType string `json:"content_type"`
+ Size int64 `json:"size"`
+ URL string `json:"url,omitempty"`
+}
diff --git a/internal/routes/routes.go b/internal/routes/routes.go
index e2cb09d..94a0128 100644
--- a/internal/routes/routes.go
+++ b/internal/routes/routes.go
@@ -471,6 +471,9 @@ func (r *Router) registerRoutes() {
r.app.Register(r.adminRoutes()...)
r.app.Register(r.adminSSERoutes()...)
+ // Documentation-only OpenAPI webhooks (events Posta POSTs to subscribers).
+ r.registerWebhookDocs()
+
// Dashboard UI (static files + SPA fallback)
webDir := r.cfg.WebDir
if info, err := os.Stat(webDir); err == nil && info.IsDir() {
diff --git a/internal/routes/webhook_docs.go b/internal/routes/webhook_docs.go
new file mode 100644
index 0000000..b78bff6
--- /dev/null
+++ b/internal/routes/webhook_docs.go
@@ -0,0 +1,60 @@
+/*
+ * Copyright 2026 Jonas Kaninda
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package routes
+
+import (
+ "net/http"
+
+ "github.com/goposta/posta/internal/dto"
+ "github.com/jkaninda/okapi"
+)
+
+func (r *Router) registerWebhookDocs() {
+
+ sigHeader := okapi.DocHeader("X-Posta-Signature", "string",
+ "HMAC-SHA256 of the raw request body, formatted as sha256=<hex>. "+
+ "Verify it against the secret returned when the webhook was created.", true)
+ uaHeader := okapi.DocHeader("User-Agent", "string", "Always \"Posta-Webhook/1.0\".", true)
+
+ received := okapi.DocResponse(200, okapi.M{"received": true})
+
+ webhook := func(name, summary string, body any) {
+ r.app.Webhook(name, http.MethodPost,
+ okapi.DocSummary(summary),
+ okapi.DocTags("Webhooks"),
+ sigHeader, uaHeader,
+ okapi.DocRequestBody(body),
+ received,
+ )
+ }
+
+ // Email lifecycle — generic {event, email_id, timestamp} payload.
+ webhook("email.sent", "Fired when a message is accepted by the destination MTA", dto.WebhookEvent{})
+ webhook("email.failed", "Fired when a message permanently fails after retries", dto.WebhookEvent{})
+
+ // Reputation signals — richer recipient-scoped payloads.
+ webhook("email.complained", "Fired when a recipient marks a message as spam", dto.ComplaintWebhookEvent{})
+ webhook("email.unsubscribed", "Fired when a recipient opts out via one-click unsubscribe", dto.UnsubscribeWebhookEvent{})
+
+ // Inbound mail — full parsed message.
+ webhook("email.inbound", "Fired when an inbound email is received and parsed", dto.InboundWebhookEvent{})
+
+ // Campaign lifecycle — {event, campaign_id, name, timestamp} payload.
+ webhook("campaign.started", "Fired when a campaign begins sending", dto.CampaignWebhookEvent{})
+ webhook("campaign.completed", "Fired when a campaign finishes sending", dto.CampaignWebhookEvent{})
+}