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
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.gonew file mode 100644index 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.goindex 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.WebDirif info, err := os.Stat(webDir); err == nil && info.IsDir() {diff --git a/internal/routes/webhook_docs.go b/internal/routes/webhook_docs.gonew file mode 100644index 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{})+}