posta - Moses Yebei

Abstract

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.

The Problem

Teams that need programmatic email sending face a binary choice: pay per-volume for SaaS providers like SendGrid or Mailgun, or assemble a fragile pipeline of Postfix, a template engine, and custom analytics. The first option leaks customer data to third parties and scales cost with every message. The second option burns engineering time on infrastructure that isn't your product.

What This Does

Posta is a self-hosted email platform that replaces both of those options. It exposes a REST API for sending transactional, batch, and templated emails, then handles SMTP delivery, inbound receiving, templates, subscriber lists, campaigns, and analytics internally. The Go backend in internal/ manages the core logic, while the web/ directory holds a Vue/TypeScript admin dashboard.

The system is built around three executables in cmd/posta/: main.go for the API server, server.go for SMTP relay and inbound handling, and worker.go for background jobs. It uses Redis and Asynq for async processing, with a PostgreSQL database for persistence. The docs/ directory contains a full Docusaurus site covering installation and every feature.

How It Is Wired

Execution starts at main in cmd/posta/main.go, which bootstraps configuration, database connections, and the HTTP router. The router in internal/routes/routes.go is the central hub—it imports 109 other modules and wires every handler to its endpoint. From there, requests flow into handlers like internal/handlers/api_key_handler.go, which is the most connected file: it touches the database, makes outbound network calls, and reads/writes files.

The call graph shows the system's true backbone. ok is called from 95 places, GetInt from 78, and FindByID from 73—these are the functions where changes ripple widest. The settings provider in internal/services/settings/provider.go is a critical dependency, called from 28 files for configuration lookups.

The system has three clear execution paths:

API requests: main → InitRoutes → handler → repository → database
Background workers: ProcessTask in internal/worker/handler.go reaches 159 functions and handles email delivery, retries, and webhooks
Cron jobs: Run in internal/cron/jobs/account_cleanup.go reaches 139 functions and handles scheduled maintenance

Three modules sit in a circular import cycle: web/src/api/client.ts, web/src/stores/auth.ts, and web/src/api/auth.ts. This makes the frontend auth flow harder to refactor than it should be.

How To Use It

Setup:

git clone https://github.com/moses-y/posta
cd posta
cp .env.example .env
docker compose up -d

Configuration: The .env.example file defines required environment variables for PostgreSQL, Redis, SMTP credentials, and JWT secrets. The compose.yml at the root orchestrates the full stack.

Running it: The Docker image built from docker/Dockerfile is the primary deployment path. For development, the Makefile provides targets for building and testing the Go binaries in cmd/posta/.

Real-World Use

A SaaS company can self-host Posta to send transactional emails—password resets, receipts, notifications—without sending customer data to a third party. The API accepts a POST to /api/v1/emails/send with an API key, returns a queued message ID, and handles delivery, retries, and bounce tracking internally. The built-in SMTP relay in internal/handlers/smtp_handler.go also lets the company receive replies and forward them to support systems via webhooks.

Code Health & Issues

Static analysis found 43 issues: 9 high, 34 medium, 0 low. The high-severity findings are:

High - Import cycle in web/src/api/client.ts, web/src/stores/auth.ts, web/src/api/auth.ts—mutually reachable modules that complicate refactoring
High - 11 oversized files, including web/src/api/types.ts at 980 lines and internal/routes/workspace_resource_routes.go
High - Hub modules: 31 modules depend on web/src/api/types.ts; churn there has high blast radius
High - Deep nesting (max depth 8) in web/src/views/domains/Domains.vue and internal/handlers/inbound_handler.go
High - 920 duplicated 6-line code blocks across 319 files, notably in cmd/posta/ and internal/config/config.go

The CI workflow pins GitHub Actions to mutable tags instead of commit SHAs, and the Docker base images (node:24-bookworm-slim, golang:1.26-alpine) aren't pinned by digest. No dependency vulnerability scan runs in CI.

The Bottom Line

Posta is a serious, feature-complete email platform with good documentation and a sane Go/Vue architecture. The main risks are the oversized files and duplicated logic in the backend, which will make maintenance harder as the codebase grows. It's a solid choice for teams that want full control over email infrastructure and are willing to operate their own stack.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

576 files

Go264
Markdown74
Vue72
TypeScript45
YAML9
JSON7

ReactVueDocker

Module dependencies

The 10 most depended-upon modules of 46, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_web_src_api_types["types"] n1_web_src_api_client["client"] n2_web_src_stores_workspace["workspace"] n3_web_src_stores_auth["auth"] n4_web_src_api_auth["auth"] n5_web_src_api_workspaces["workspaces"] n6_web_src_router_index["index"] n7_web_src_api_admin["admin"] n8_web_src_api_analytics["analytics"] n9_web_src_api_apikeys["apikeys"] n7_web_src_api_admin --> n1_web_src_api_client n7_web_src_api_admin --> n0_web_src_api_types n8_web_src_api_analytics --> n1_web_src_api_client n8_web_src_api_analytics --> n0_web_src_api_types n9_web_src_api_apikeys --> n1_web_src_api_client n9_web_src_api_apikeys --> n0_web_src_api_types n4_web_src_api_auth --> n1_web_src_api_client n4_web_src_api_auth --> n0_web_src_api_types n1_web_src_api_client --> n3_web_src_stores_auth n5_web_src_api_workspaces --> n1_web_src_api_client n5_web_src_api_workspaces --> n0_web_src_api_types n6_web_src_router_index --> n3_web_src_stores_auth n6_web_src_router_index --> n2_web_src_stores_workspace n3_web_src_stores_auth --> n4_web_src_api_auth n3_web_src_stores_auth --> n0_web_src_api_types n2_web_src_stores_workspace --> n1_web_src_api_client n2_web_src_stores_workspace --> n5_web_src_api_workspaces n2_web_src_stores_workspace --> n0_web_src_api_types classDef cyc stroke:#ef4444,stroke-width:2px; class n1_web_src_api_client,n3_web_src_stores_auth,n4_web_src_api_auth cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium4

low2

Pin third-party GitHub Actions to a commit SHAhigh5 occurrences

.github/workflows

docker/setup-buildx-action@v3, docker/build-push-action@v6, golangci/golangci-lint-action@v7, docker/setup-qemu-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium3 occurrences

docker/Dockerfile

node:24-bookworm-slim, golang:1.26-alpine, alpine:3.21

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/ci.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.