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
fix(routes): give clashing operations unique OpenAPI operation IDs
Jonas Kaninda5b2ae32f2137
diff --git a/internal/config/config.go b/internal/config/config.goindex b32a523..6f586be 100644--- a/internal/config/config.go+++ b/internal/config/config.go@@ -438,6 +438,29 @@ func (c *Config) validateWorker() error {warnRemovedEnvVars()return c.ValidateWorker()}+// OpenAPISecuritySchemes are the security schemes the API documentation+// declares. Routes reference them by name with WithSecurity.+func OpenAPISecuritySchemes() okapi.SecuritySchemes {+ return okapi.SecuritySchemes{+ // Dashboard / JWT-authenticated endpoints.+ {+ Name: "BearerAuth",+ Description: "Bearer token issued by /auth/login. Send as: `Authorization: Bearer <JWT>`.",+ Type: "http",+ Scheme: "bearer",+ BearerFormat: "JWT",+ },+ // API-key authenticated endpoints.+ {+ Name: "ApiKeyAuth",+ Description: "Long-lived API key. Send as: `Authorization: Bearer <API_KEY>`. Manage keys under Settings → API Keys.",+ Type: "http",+ Scheme: "bearer",+ BearerFormat: "Posta API Key",+ },+ }+}+func (c *Config) Initialize(app *okapi.Okapi) error {if err := c.validate(); err != nil {return err@@ -470,22 +493,7 @@ func (c *Config) Initialize(app *okapi.Okapi) error {})if c.OpenAPIDocs {- // Dashboard / JWT-authenticated endpoints.- c.securitySchemes = append(c.securitySchemes, okapi.SecurityScheme{- Name: "BearerAuth",- Description: "Bearer token issued by /auth/login. Send as: `Authorization: Bearer <JWT>`.",- Type: "http",- Scheme: "bearer",- BearerFormat: "JWT",- })- // API-key authenticated endpoints.- c.securitySchemes = append(c.securitySchemes, okapi.SecurityScheme{- Name: "ApiKeyAuth",- Description: "Long-lived API key. Send as: `Authorization: Bearer <API_KEY>`. Manage keys under Settings → API Keys.",- Type: "http",- Scheme: "bearer",- BearerFormat: "Posta API Key",- })+ c.securitySchemes = append(c.securitySchemes, OpenAPISecuritySchemes()...)app.WithOpenAPIDocs(okapi.OpenAPI{Title: "Posta API",Version: Version,diff --git a/internal/routes/admin_routes.go b/internal/routes/admin_routes.goindex 742863c..5e76e30 100644--- a/internal/routes/admin_routes.go+++ b/internal/routes/admin_routes.go@@ -514,6 +514,7 @@ func (r *Router) adminRoutes() []okapi.RouteDefinition {Path: "/workspaces/{id:int}/plan",Handler: okapi.H(r.h.plan.GetWorkspacePlan),Group: adminGroup,+ OperationId: "admin-get-workspace-plan",Summary: "Get workspace plan",Description: "Get the effective plan for a workspace",Response: &dto.Response[models.Plan]{},diff --git a/internal/routes/openapi_test.go b/internal/routes/openapi_test.gonew file mode 100644index 0000000..033444b--- /dev/null+++ b/internal/routes/openapi_test.go@@ -0,0 +1,65 @@+// 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 routes++import (+ "testing"++ "github.com/goposta/posta/internal/config"+ "github.com/jkaninda/okapi"+)++// The server validates the OpenAPI document at startup and only logs a+// warning, so a broken document (two operations with one operationId, an+// undeclared security scheme) would otherwise ship unnoticed. okapi derives+// an operationId from the summary, so two routes with the same summary clash.+func TestOpenAPIDocumentIsValid(t *testing.T) {+ app := okapi.New().WithOpenAPIDocs(okapi.OpenAPI{+ Title: "Posta API",+ Version: "test",+ SecuritySchemes: config.OpenAPISecuritySchemes(),+ })+ r := &Router{+ app: app,+ cfg: &config.Config{InboundEnabled: true, MessagesEnabled: true},+ v1: app.Group("/api/v1"),+ }+ app.Register(r.healthRoutes()...)+ app.Register(r.infoRoute())+ app.Register(r.authRoutes()...)+ app.Register(r.apiAuthRoutes()...)+ app.Register(r.userRoutes()...)+ app.Register(r.workspaceRoutes()...)+ app.Register(r.workspaceResourceRoutes()...)+ app.Register(r.oauthRoutes()...)+ app.Register(r.trackingRoutes()...)+ app.Register(r.trackingAnalyticsRoutes()...)+ app.Register(r.bounceWebhookRoutes()...)+ app.Register(r.inboundWebhookRoutes()...)+ app.Register(r.inboundWorkspaceRoutes()...)+ app.Register(r.formIngestRoutes()...)+ app.Register(r.messageWorkspaceRoutes()...)+ app.Register(r.adminSSERoutes()...)+ app.Register(r.adminRoutes()...)++ if err := app.ValidateOpenAPI(); err != nil {+ t.Fatal(err)+ }+}diff --git a/internal/routes/workspace_resource_routes.go b/internal/routes/workspace_resource_routes.goindex ed22cb2..7160818 100644--- a/internal/routes/workspace_resource_routes.go+++ b/internal/routes/workspace_resource_routes.go@@ -81,18 +81,20 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {Path: "/emails",Handler: okapi.H(r.h.email.List),Group: opsGroup,+ OperationId: "workspace-list-emails",Summary: "List emails",Description: "List sent emails with pagination",Request: &handlers.ListRequest{},Response: &dto.PageableResponse[models.Email]{},},{- Method: http.MethodGet,- Path: "/emails/{id}",- Handler: okapi.H(r.h.email.Get),- Group: opsGroup,- Summary: "Get email details",- Response: &dto.Response[models.Email]{},+ Method: http.MethodGet,+ Path: "/emails/{id}",+ Handler: okapi.H(r.h.email.Get),+ Group: opsGroup,+ OperationId: "workspace-get-email-details",+ Summary: "Get email details",+ Response: &dto.Response[models.Email]{},Options: []okapi.RouteOption{okapi.DocPathParam("id", "string", "Email UUID"),okapi.DocResponse(404, &dto.ErrorResponseBody{}),@@ -103,6 +105,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {Path: "/emails/{id}/status",Handler: okapi.H(r.h.email.GetStatus),Group: opsGroup,+ OperationId: "workspace-get-email-delivery-status",Summary: "Get email delivery status",Description: "Returns a lightweight status view for polling email delivery progress. Only the email owner can access this.",Response: &dto.Response[handlers.EmailStatusResponse]{},@@ -116,6 +119,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {Path: "/emails/{id}/retry",Handler: okapi.H(r.h.email.Retry),Group: opsGroup,+ OperationId: "workspace-retry-failed-email",Summary: "Retry failed email",Description: "Re-enqueue a failed email for another delivery attempt",Response: &dto.Response[email.SendResponse]{},@@ -130,6 +134,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {Path: "/emails/preview",Handler: okapi.H(r.h.email.Preview),Group: opsGroup,+ OperationId: "workspace-preview-email-from-template",Summary: "Preview email from template",Description: "Render a template with variables and return the HTML, text, and subject without sending.",Request: &handlers.PreviewEmailRequest{},@@ -704,33 +709,36 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {},},{- Method: http.MethodPost,- Path: pathWebhooks,- Handler: okapi.H(r.h.webhook.Create),- Group: opsGroup,- Tags: []string{tagUser},- Summary: "Create webhook",- Request: &handlers.CreateWebhookRequest{},+ Method: http.MethodPost,+ Path: pathWebhooks,+ Handler: okapi.H(r.h.webhook.Create),+ Group: opsGroup,+ Tags: []string{tagUser},+ OperationId: "workspace-create-webhook",+ Summary: "Create webhook",+ Request: &handlers.CreateWebhookRequest{},Options: []okapi.RouteOption{okapi.DocResponse(201, &dto.Response[models.Webhook]{}),},},{- Method: http.MethodGet,- Path: pathWebhooks,- Handler: okapi.H(r.h.webhook.List),- Group: opsGroup,- Summary: "List webhooks",- Request: &handlers.ListRequest{},- Response: &dto.PageableResponse[models.Webhook]{},+ Method: http.MethodGet,+ Path: pathWebhooks,+ Handler: okapi.H(r.h.webhook.List),+ Group: opsGroup,+ OperationId: "workspace-list-webhooks",+ Summary: "List webhooks",+ Request: &handlers.ListRequest{},+ Response: &dto.PageableResponse[models.Webhook]{},},{- Method: http.MethodDelete,- Path: "/webhooks/{id:int}",- Handler: okapi.H(r.h.webhook.Delete),- Group: opsGroup,- Tags: []string{tagUser},- Summary: "Delete webhook",+ Method: http.MethodDelete,+ Path: "/webhooks/{id:int}",+ Handler: okapi.H(r.h.webhook.Delete),+ Group: opsGroup,+ Tags: []string{tagUser},+ OperationId: "workspace-delete-webhook",+ Summary: "Delete webhook",Options: []okapi.RouteOption{okapi.DocPathParam("id", "integer", "Webhook ID"),okapi.DocResponse(204, nil),@@ -738,13 +746,14 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {},},{- Method: http.MethodGet,- Path: "/webhook-deliveries",- Handler: okapi.H(r.h.webhookDelivery.List),- Group: opsGroup,- Summary: "List webhook deliveries",- Request: &handlers.ListRequest{},- Response: &dto.PageableResponse[models.WebhookDelivery]{},+ Method: http.MethodGet,+ Path: "/webhook-deliveries",+ Handler: okapi.H(r.h.webhookDelivery.List),+ Group: opsGroup,+ OperationId: "workspace-list-webhook-deliveries",+ Summary: "List webhook deliveries",+ Request: &handlers.ListRequest{},+ Response: &dto.PageableResponse[models.WebhookDelivery]{},},{Method: http.MethodPost,@@ -819,13 +828,14 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {},},{- Method: http.MethodGet,- Path: pathBounces,- Handler: okapi.H(r.h.bounce.List),- Group: opsGroup,- Summary: "List bounces",- Request: &handlers.ListRequest{},- Response: &dto.PageableResponse[models.Bounce]{},+ Method: http.MethodGet,+ Path: pathBounces,+ Handler: okapi.H(r.h.bounce.List),+ Group: opsGroup,+ OperationId: "workspace-list-bounces",+ Summary: "List bounces",+ Request: &handlers.ListRequest{},+ Response: &dto.PageableResponse[models.Bounce]{},},{Method: http.MethodPost,@@ -1104,6 +1114,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {Handler: okapi.H(r.h.subscriberList.UnsubscribeByEmail),Group: opsGroup,Tags: []string{tagSubscriberLists},+ OperationId: "workspace-unsubscribe-an-email-from-a-list",Summary: "Unsubscribe an email from a list",Description: "API-key-accessible list opt-out. Idempotent. Does not change global subscriber status.",Request: &handlers.ListUnsubscribeByEmailRequest{},@@ -1116,6 +1127,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {Handler: okapi.H(r.h.subscriberList.ResubscribeByEmail),Group: opsGroup,Tags: []string{tagSubscriberLists},+ OperationId: "workspace-re-subscribe-an-email-to-a-list",Summary: "Re-subscribe an email to a list",Description: "Reverses a list-scoped opt-out and re-adds to the list (static lists). Idempotent.",Request: &handlers.ListResubscribeByEmailRequest{},